> ## Documentation Index
> Fetch the complete documentation index at: https://voyant.travel/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive Connect events on your own endpoint, and verify that each delivery came from Voyant.

# Webhooks

A webhook subscription tells Connect to `POST` matching events to an endpoint you run. Manage subscriptions with the `webhookSubscriptions` resource in the [Connect SDK](https://voyant.travel/docs/connect/connect-sdk.md) or the Connect API reference.

## Endpoint requirements

Connect checks the endpoint URL when you create or update a subscription, and again before every delivery. The URL must:

* use `https`
* not include a user name or password
* resolve only to public addresses, not private, loopback, link-local, or cloud metadata ranges
* not point at a Voyant host, such as `voyant.travel`, `onvoyant.com`, `onvoyant.net`, or `voyanthub.com`, or any of their subdomains

A delivery to a URL that no longer meets these rules is recorded as failed and is not sent.

Connect does not follow redirects. Your endpoint must answer with a `2xx` status. A `3xx` response counts as a failed delivery, so point the subscription at the final URL.

## Delivery headers

Every delivery carries these headers:

| Header | Value |
| - | - |
| `Content-Type` | `application/json` |
| `X-Webhook-Event` | The event type, for example `booking.confirmed`. |
| `X-Webhook-Timestamp` | When the event happened, as an ISO 8601 timestamp. |
| `X-Webhook-Delivery-Timestamp` | When this delivery attempt was signed, in Unix seconds. |
| `X-Webhook-Signature-V2` | `sha256=` followed by the hex HMAC-SHA256 of `{X-Webhook-Delivery-Timestamp}.{raw body}`, keyed with the subscription secret. |
| `X-Webhook-Signature` | `sha256=` followed by the hex HMAC-SHA256 of the raw body alone. Kept for existing integrations. |

Custom headers you configure on a subscription are sent too. They cannot set or replace the signature or timestamp headers above, and a subscription that tries is rejected.

## Verify a delivery

Verify `X-Webhook-Signature-V2`. It binds the signature to the delivery time, so you can reject a delivery that is replayed later.

1. Read the raw request body as bytes, before any JSON parsing.
2. Read `X-Webhook-Delivery-Timestamp`. Reject the request if it is more than five minutes away from your current time.
3. Compute the HMAC-SHA256 of `{timestamp}.{raw body}` with your subscription secret and hex-encode it.
4. Compare `sha256={your digest}` with `X-Webhook-Signature-V2` using a constant-time comparison.

```ts theme={null}
import { createHmac, timingSafeEqual } from "node:crypto"

const TOLERANCE_SECONDS = 300

export function verifyConnectWebhook(
  secret: string,
  rawBody: string,
  headers: Headers,
): boolean {
  const timestamp = headers.get("x-webhook-delivery-timestamp") ?? ""
  const signature = headers.get("x-webhook-signature-v2") ?? ""
  const seconds = Number(timestamp)
  if (!Number.isInteger(seconds)) return false
  if (Math.abs(Date.now() / 1000 - seconds) > TOLERANCE_SECONDS) return false

  const expected = `sha256=${createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex")}`
  const actualBytes = Buffer.from(signature)
  const expectedBytes = Buffer.from(expected)
  return (
    actualBytes.length === expectedBytes.length &&
    timingSafeEqual(actualBytes, expectedBytes)
  )
}
```

> [!NOTE]
>
> `X-Webhook-Signature` signs the body without a timestamp, so it cannot tell a fresh delivery from a replayed one. It stays in place so current receivers keep working. Move your verification to `X-Webhook-Signature-V2`. The older header will be retired in a later release.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.