> ## 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

> Send business events from Voyant to your own systems: add an endpoint, verify the signature, handle retries, and resend deliveries.

Webhooks send business events, such as a confirmed booking or an issued invoice, to an HTTPS address on your server. Each delivery is signed, retried on failure, and recorded so you can resend it.

## Add an endpoint

You need the **Manage webhooks** permission.

**1. Open the settings**

In the admin, go to **Settings**, then **Webhooks**, and click **Add endpoint**.

**2. Fill in the form**

Enter the **Endpoint URL** and an optional **Description**, then select the **Events** to receive. Select at least one event.

**3. Copy the signing secret**

Click **Add endpoint**. Voyant shows the signing secret once, so copy it and store it on your server. It starts with `whsec_`.

**4. Send a test event**

Open the endpoint and click **Send test event**. The result appears under **Recent deliveries**.

The endpoint URL must use HTTPS and must point to a public address. Voyant refuses private addresses, URLs that include a user name or password, and URLs with a fragment.

## What Voyant sends

Each delivery is a `POST` request with a JSON body:

```json theme={null}
{
  "data": {
    "entity_id": "book_01m1w67g5ke84r2n2nywpfe8b8",
    "entity_module": "bookings",
    "occurred_at": "2026-11-01T09:30:00.000Z"
  },
  "emittedAt": "2026-11-01T09:30:00.000Z",
  "metadata": {
    "eventId": "catalog.booking.committed:evt_01m1w6a2b3c4d5e6f7g8h9j0k1",
    "graphEventId": "@voyant-travel/catalog#event.booking.committed",
    "graphEventVersion": "1.0.0"
  },
  "name": "catalog.booking.committed"
}
```

| Field | Meaning |
| - | - |
| `name` | The event name. |
| `data` | The event's fields. Only the fields listed for that event are sent. |
| `emittedAt` | When the event happened, as an ISO 8601 timestamp. |
| `metadata.eventId` | The event's unique ID. |
| `metadata.graphEventId` | The stable ID of the event's definition. |
| `metadata.graphEventVersion` | The version of the event's definition. |
| `metadata.correlationId`, `metadata.causationId` | Sent when the event has them. |

Events carry IDs and short facts, not whole records. To get the full record, read it from the [Admin API](https://voyant.travel/docs/guides/consume-the-api.md).

These headers come with each delivery:

| Header | Value |
| - | - |
| `content-type` | `application/json` |
| `x-voyant-signature` | The signature, as `sha256=` followed by a hex digest. |
| `x-voyant-timestamp` | The time of this attempt, in Unix seconds. |
| `x-voyant-event` | The event name. |
| `x-voyant-event-id` | The same value as `metadata.eventId`. |
| `x-voyant-event-contract` | The same value as `metadata.graphEventId`. |
| `x-voyant-event-version` | The same value as `metadata.graphEventVersion`. |
| `idempotency-key` | The key for this delivery. Retries keep it, and a resend gets a new one. |

## Verify the signature

The signature is an HMAC-SHA256 of the timestamp, a period, and the raw request body. The key is the whole signing secret, including `whsec_`.

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

const TOLERANCE_SECONDS = 300

export function verifyVoyantWebhook({ rawBody, timestamp, signature, secret }) {
  const sentAt = Number(timestamp)
  if (!Number.isInteger(sentAt)) return false
  if (Math.abs(Date.now() / 1000 - sentAt) > TOLERANCE_SECONDS) return false

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

Pass the `x-voyant-timestamp` header as `timestamp` and the `x-voyant-signature` header as `signature`. If the function returns `false`, answer with a `400`.

* Use the raw body, exactly as you received it. Parsing the JSON and serializing it again can change the bytes and break the signature.
* Check the timestamp. It stops an old request from being sent again later. Each retry is signed again with a new timestamp, so retries still pass.

## Retries and failures

Answer with any `2xx` status within 15 seconds. Voyant follows up to 3 redirects.

| Result of an attempt | What Voyant does |
| - | - |
| `2xx` | Marks the delivery **Delivered**. |
| `408`, `429`, or `5xx` | Retries. |
| A timeout or a network error | Retries. |
| Any other status | Stops. There is no retry. |
| The URL is not allowed, or there are too many redirects | Stops. There is no retry. |

* **Number of retries:** 5 by default and 10 at most. The admin form uses the default. To set another number, send `maxRetries` to the [Admin API](#manage-endpoints-with-the-api).
* **Wait between retries:** the wait starts at 1 second and doubles each time, up to 60 seconds. These are minimum waits, so a retry can go out later.
* **After the last retry:** Voyant stops and marks the delivery **Gave up**. The event is not sent again unless you resend it.

An endpoint shows **Failing** after a delivery gives up. The badge clears at the next successful delivery. Voyant does not disable a failing endpoint. Attempts still waiting when you disable an endpoint also end as **Gave up**.

### Handle duplicates and order

A delivery can arrive more than once. For example, your server may finish the work but answer after the timeout. To process each event once, store `x-voyant-event-id` and skip events you have already handled. Do not rely on events arriving in order.

## Check, test, and resend

Open an endpoint in **Settings**, then **Webhooks**.

* **Recent deliveries** lists each attempt: the event, its status, the attempt number, the response status or error, and the time. The status is **Queued**, **Sending**, **Delivered**, **Failed**, or **Gave up**. **Failed** means this attempt failed. Another may follow.
* **Send test event** sends a sample of the first event selected on the endpoint. The fields hold sample values, and the event ID starts with `evt_test_`. The endpoint must be enabled.
* **Resend** on a delivery sends the same event again, with the same event ID and a new `idempotency-key`. The endpoint must be enabled and must still have that event selected. If you skip events you have already handled, clear that record first, or the resend does nothing.
* **Disable** stops new events. **Enable** starts them again. Events from the time in between are not sent later.
* **Rotate secret** replaces the signing secret. The old one stops working right away, with no overlap, so update your server at the same time.
* **Delete endpoint** stops the events and removes the endpoint.

## Events

These events can be selected on an endpoint and are sent today. The event picker can list a few other names that Voyant does not send yet.

### Bookings

| Event | Sent when | `data` |
| - | - | - |
| `catalog.booking.committed` | A booking is confirmed. A booking placed on hold sends this only when the hold is confirmed. | `entity_module`, `entity_id`, `occurred_at` |
| `catalog.booking.cancelled` | A booking is canceled with the cancel action. A manual correction of the booking status does not send it. | `entity_module`, `entity_id`, `occurred_at` |
| `catalog.booking.conversion` | A booking from a booking session with a sales channel or a website handoff is confirmed or canceled. A booking your staff make is also sent when its customer came from a website handoff in the last 90 days. See [Bookings your staff make](#bookings-your-staff-make). | `eventId`, `occurredAt`, `bookingId`, `bookingSessionId`, `sessionCreatedAt`, `channelId`, `handoffRef`, `lifecycleState`, `totalCents`, `currency`, `productId`, `departureId`, and `match` when sent |
| `catalog.booking.offline_conversion` | A booking your staff make is confirmed or canceled, no website visit reported it, and its customer has agreed to personalized ads (or, if you chose legitimate interest, has not objected). See [Bookings from a call or WhatsApp](#bookings-from-a-call-or-whatsapp). | `eventId`, `occurredAt`, `bookingId`, `lifecycleState`, `totalCents`, `currency`, `productId`, `departureId`, `sourceType`, `basis`, and `match` when sent |
| `catalog.booking.journey` | A booking session that came from a website handoff is created, gets a quote, records the shopper's contact, or places a hold. | `eventId`, `occurredAt`, `sessionCreatedAt`, `bookingSessionId`, `channelId`, `handoffRef`, `stage`, `productId`, and `match` on `contact_completed` when sent |

### Products, prices, and availability

| Event | Sent when | `data` |
| - | - | - |
| `catalog.entity.created` | A product is created. | `entity_module`, `entity_id`, `occurred_at` |
| `catalog.entity.updated` | A product, its content, its media, or where it is published changes. | `entity_module`, `entity_id`, `occurred_at` |
| `catalog.entity.deleted` | A product is deleted. | `entity_module`, `entity_id`, `occurred_at` |
| `catalog.entity.price.changed` | A price rule on a product option, or a per-unit price in that rule, is created, updated, or deleted. | `entity_module`, `entity_id`, `occurred_at` |
| `catalog.entity.availability.changed` | A departure's availability changes, for example after a booking, a cancellation, or a manual edit. | `entity_module`, `entity_id`, `occurred_at` |

For these events and the first two booking events, `entity_id` is the ID of the product or booking, and `entity_module` is `products` or `bookings`.

> [!NOTE]
>
> `catalog.entity.price.changed` covers price rules only. Tiers, departure price overrides, pickup prices, start time rules, and supplier prices do not send it. If you show prices from those sources, read them again on your own schedule.

### Invoices and payments

| Event | Sent when | `data` |
| - | - | - |
| `invoice.issued` | An invoice is issued. | `invoiceId`, `invoiceType`, and, when they apply, `skipExternalSync` and `convertedFromInvoiceId` |
| `invoice.proforma.issued` | A proforma invoice is issued. | Same as `invoice.issued` |
| `invoice.proforma.converted` | A proforma invoice becomes a final invoice. | `invoiceId`, `invoiceType`, `occurredAt`, `lineage` |
| `invoice.voided` | An invoice is voided. | `invoiceId`, `invoiceType`, `occurredAt` |
| `credit_note.issued` | A draft credit note is issued against an invoice. | `creditNoteId`, `creditNoteNumber`, `issueDate`, `currency`, `reason`, totals (`totalCents`, `subtotalCents`, `taxCents`), `lineItems` (description, quantity, unit price, total, tax rate, VAT treatment), `reversesInvoiceInFull`, and the original invoice: `invoiceId`, `invoiceNumber`, `invoiceIssueDate`, `invoiceTotalCents`, `invoiceStatus`, and `invoiceExternalDocument` when your invoicing provider holds it. `invoiceExternalDocumentPending` is `true` while your invoicing provider has not numbered the invoice yet: its document is still to come, so reverse it once the invoice is numbered. With `invoiceExternalDocumentPending` `false` and no `invoiceExternalDocument`, the invoice has no document in your provider to reverse |
| `invoice.manual-adoption.requested` | An invoice needs matching to a document that already exists in your invoicing provider. | `invoiceId`, `invoiceType`, `intentId`, `provider`, `occurredAt` |
| `invoice.payment.recorded` | A payment is recorded on an invoice. | Invoice totals, plus `paymentId`, `amountCents`, `currency`, `paymentMethod`, `paymentDate`, `occurredAt`, and others |
| `invoice.payment.deleted` | A payment is removed from an invoice. | Same as `invoice.payment.recorded` |
| `invoice.payment.refunded` | A refund is settled, whether returned to the card or paid another way. | `refundSettlementId`, `paymentId`, `invoiceId`, `creditNoteId`, `bookingId`, `method`, `amountCents`, `currency`, `processorReference`, `settledAt`, `occurredAt` |
| `finance.booking.payment` | Money received or returned for a booking changes: a payment is recorded, changed or removed, a card payment completes, or a refund is settled. Also sent once when a booking is created. | `eventId`, `occurredAt`, `bookingId`, `paymentState` (`unpaid`, `partially_paid`, `paid`, `partially_refunded` or `refunded`), `paidCents`, `refundedCents`, `currency` |

### Inquiries

| Event | Sent when | `data` |
| - | - | - |
| `relationships.inquiry.conversion` | An inquiry that came from a website handoff is accepted, qualified, or converted. | `eventId`, `occurredAt`, `inquiryCreatedAt`, `inquiryId`, `sourceRef`, `lifecycleState`, `targetKind`, `targetId`, and `match` when sent |

### Marketing consent

| Event | Sent when | `data` |
| - | - | - |
| `relationships.person.marketing_consent.withdrawn` | A customer withdraws marketing consent, or objects to being measured for ads: your staff record it with **Record withdrawal** or **Record objection** on the customer's page in **People**. | `personId`, `purposes` (`messages`, `advertising` or both), `occurredAt`, `source`, and `match` when sent |

If you uploaded a customer's hashed email or phone to an ad platform, for example to a Meta custom audience, remove it when this event arrives with `advertising` in `purposes`. `match` carries the same hashes as the conversion events, so you can find the customer without their readable contact. The event ID is `evt_relationships_person_marketing_consent_withdrawn_<entryId>`, sent once per withdrawal. A withdrawal that is not saved sends nothing.

### Website attribution events

`catalog.booking.journey`, `catalog.booking.conversion` and `relationships.inquiry.conversion` tell your website what happened to a visit it handed to Voyant with a `handoff_ref`. The booking engine accepts `handoff_ref` on product links (`/`), trip links for flights and packages (`/trip`), and hotel itinerary links (`/stays`). Each link also keeps Google's `_gl` parameter and a `return_to` address on your own site, where a shopper who has paid is sent back.

#### Journey stages

`stage` is one of these values, in the order a shopper reaches them:

| Stage | Sent when |
| - | - |
| `session_created` | The shopper opens the booking engine. |
| `quote_created` | The booking engine prices the selection. |
| `contact_completed` | The shopper first leaves an email or phone together with acceptance of your privacy policy. This is when your team can reach them. It is sent once for each booking session, before any `hold_placed`, and editing the contact later sends nothing new. A shopper who leaves before this sends nothing. Its `eventId` is `evt_catalog_booking_journey_<bookingSessionId>_contact_completed`. |
| `hold_placed` | The booking engine holds the places, just before payment. |

`productId` is `null` for a trip of flights or packages, which has no single product. Trip bookings send one `catalog.booking.conversion` for each booking the trip makes.

When your staff answer an inquiry from a website handoff with a proposal and the customer accepts it, the booking keeps that inquiry's `handoffRef`. Its `catalog.booking.conversion` carries the same reference as the inquiry's `relationships.inquiry.conversion`. Join it to `finance.booking.payment` on `bookingId` to see the money received for it.

#### The contact stage in your tag manager

The booking engine also tells your Google Tag Manager container when a shopper reaches `contact_completed` on a product booking, so your ad platforms can count it as a lead. It pushes this to the data layer:

```js theme={null}
{
  event: "engine.contact.submitted",
  voyantJourney: {
    booking_session_id: "…",
    product_id: "…",
    departure_id: "…",
    step: "contact",
    channel: "…"
  }
}
```

* It carries no email, phone or name.
* It is pushed once for each booking session, even if the shopper goes back and continues again.
* It is pushed only when the shopper has allowed **marketing** cookies. With marketing cookies refused, or no choice made, nothing is pushed.
* When the booking engine uses the consent from your website, your container loads only after the shopper has allowed analytics or marketing cookies on your website. Add your container ID under **Settings**, then **Cookie consent**.

The booking engine does not load the Meta Pixel script. To send the lead to Meta, add a **Custom Image** tag that fires on the custom event `engine.contact.submitted` and requires ad storage consent, with this image URL:

```
https://www.facebook.com/tr?id=<your pixel ID>&ev=Lead&noscript=1&eid=evt_catalog_booking_journey_{{DLV booking_session_id}}_contact_completed
```

`DLV booking_session_id` is a Data Layer Variable for `voyantJourney.booking_session_id`. The `eid` is the same event ID as the webhook's `contact_completed` stage, so if you also send that lead to Meta from your server, Meta counts it once.

#### Bookings your staff make

Many customers leave a contact on your website and book later by phone. When your staff confirm or cancel a booking in the admin, Voyant looks for the customer (the booking's billing contact or lead traveler, matched by email first, then by phone) and for that customer's most recent booking session from a website handoff in the 90 days before the booking was confirmed. If there is one, Voyant sends `catalog.booking.conversion` with that session's `bookingSessionId`, `sessionCreatedAt`, `handoffRef` and `channelId`, and the booking's own `bookingId`, total and currency. If there is none, `catalog.booking.conversion` is not sent; see the next section. Your staff do nothing extra.

Each booking sends one `confirmed` event at most, with the event ID `evt_catalog_booking_conversion_<bookingId>_confirmed`, however often the booking is changed later. A booking made through the booking engine is reported by its own session and never twice. A correction made more than 7 days after the booking was confirmed, or canceled, is not sent again.

#### Bookings from a call or WhatsApp

Many customers see an ad, then call or message you on WhatsApp and never open the booking engine. Your staff make the booking in the admin. When that booking is confirmed or canceled, no booking session made it, and no website visit was found for its customer, Voyant sends `catalog.booking.offline_conversion` if the customer has agreed to personalized ads, or, if you chose legitimate interest, unless the customer objected. Ad platforms do not need a website visit to credit the booking: the hashed email or phone in `match` is enough. With Meta's Conversions API, for example, send it with `action_source` `phone_call` or `system_generated`.

* **Who counts.** The customer is the booking's billing person, or its lead traveler's person when it is billed to a company or to no one. Their consent is read from **Marketing consent** on their page in **People** when the booking is confirmed or canceled. A customer who agreed outside the booking engine, for example in a signed contract or a WhatsApp reply, counts once your staff record it there with **Record consent** and say where the agreement can be found. After a withdrawal, later bookings send nothing.
* **On which basis.** Open **Settings**, then **Webhooks**, and choose under **Bookings from calls and messages**:

  * **Only with the customer's consent** (the default). Sent only while the customer's consent to personalized ads is on record.
  * **Legitimate interest, unless the customer objects.** Sent for customers with no consent and no objection on record, so nobody has to record consent for every sale. Say so in your privacy policy. Choosing it asks where your legitimate interest assessment can be found, and the change is kept with who made it and when. A customer who objects is recorded with **Record objection** on their page in **People**, and their later bookings send nothing.

  `basis` says which applied: `consent` or `legitimate_interest_measurement`. A customer whose consent is on record is always sent as `consent`. Use `legitimate_interest_measurement` events for conversion reporting only: never add their hashes to an ad platform audience.
* **Whose contact.** `match` hashes that customer's own email and phone: from their record in **People** first, then the contact the booking holds for them. Another traveler's contact is never hashed.
* **What it carries.** The booking's `bookingId`, `lifecycleState`, total, currency, the first product and departure, and `sourceType` (how the booking was made, for example `manual`). There is no session, handoff or channel, because there was no visit.
* **Once.** The event ID is `evt_catalog_booking_offline_conversion_<bookingId>_<state>`. A booking that `catalog.booking.conversion` reports never also sends this event. A booking made through the booking engine never sends it either: the engine and your website measure those.

Phone numbers your staff type in the admin are saved with the country code. The phone field starts on your country, from your default market, and shows the country so staff can change it.

#### Hashed contact for ad matching

These five events can carry a `match` object, so your ad platforms can match a lead or a booking to the person who clicked your ad:

```json theme={null}
"match": {
  "emailSha256": "<64 lower-case hex characters>",
  "phoneSha256": "<64 lower-case hex characters>"
}
```

* `emailSha256` is the SHA-256 hash of the email, trimmed and lower-cased.
* `phoneSha256` is the SHA-256 hash of the phone as digits only, with the country code and without `+` or leading zeros (for example `40712345678`). A phone saved without a country code, such as `0712 345 678` or `+0712 345 678`, has no `phoneSha256`, because Voyant does not guess the country.
* The readable email and phone are never sent. Either field, or the whole object, is left out when there is nothing to hash.

`match` is on the `contact_completed` journey stage, on booking conversions, on offline conversions, on inquiry conversions in all three states, and on marketing consent withdrawals. For a booking session the contact is the one the shopper entered. For a booking your staff make it is the customer's. For an inquiry it is the inquiry's contact, or its customer's once the inquiry is linked to one.

Sending the hashes is on unless you turn it off. To turn it off, open **Settings**, then **Webhooks**, and switch off **Send hashed email and phone** under **Ad matching**. Whether to share them is your privacy decision: check that your privacy policy covers it, and send the hashes on to an ad platform only for visitors who gave marketing consent.

#### Customer lists for ad audiences

The events above report one booking at a time. To build a customer list audience, for example to show this season's trips to past travelers, to stop showing a trip to people who just booked it, or to find people who resemble your buyers, read the whole list instead:

```
GET https://{workspace}.onvoyant.com/api/v1/admin/advertising-audience?limit=100&cursor=<nextCursor>
```

Each row is one customer whose consent to personalized ads stands:

| Field | Meaning |
| - | - |
| `personId` | The customer's ID, so you can track who is added and removed |
| `match` | `emailSha256` and `phoneSha256`, hashed exactly as above |
| `consentedAt` | When the customer agreed to personalized ads |
| `lastBookingAt` | When their latest confirmed booking was confirmed, or `null` |
| `bookingCount` | Confirmed bookings that are not canceled |
| `productIds`, `destinationIds`, `productTypes` | What those bookings were for |

* **Consent only.** A customer who never agreed, or who withdrew, is not listed. Neither is a customer whose bookings you measure under legitimate interest: that basis covers measuring conversions, not targeting.
* **No readable contact details.** No names, emails or phones. A customer with no email or phone that can be hashed is left out. With **Send hashed email and phone** switched off, the list is empty.
* **A full snapshot.** Read every page, following `nextCursor` until it is `null`, and compare it with your previous copy to add and remove people. A customer who withdraws is missing from the next read.
* **Its own permission.** The token needs `advertising-audience:read`. That permission reads this list and nothing else, and no other permission, not even full access on a token, includes it. A marketing tool never needs to read your customers or bookings in the clear.

## Manage endpoints with the API

The same actions are available under `https://{workspace}.onvoyant.com/api/v1/admin/webhooks`. The token needs the `webhooks` permission: `read`, `write`, or `delete`. See [Consume the API](https://voyant.travel/docs/guides/consume-the-api.md) for tokens.

| Request | Action |
| - | - |
| `GET /events` | List the events with the fields of each one. |
| `GET /subscriptions`, `POST /subscriptions` | List or create endpoints. The create response holds the signing secret, once. |
| `GET`, `PATCH`, or `DELETE /subscriptions/{id}` | Read, change, or delete an endpoint. |
| `POST /subscriptions/{id}/enable`, `/disable` | Enable or disable an endpoint. |
| `POST /subscriptions/{id}/rotate-secret` | Replace the signing secret. |
| `POST /subscriptions/{id}/test` | Send a test event. |
| `GET /deliveries?subscriptionId={id}` | List recent deliveries, 50 by default and 200 at most. |
| `POST /deliveries/{id}/replay` | Resend a delivery. |

## Next steps

> [card] [Consume the API](https://voyant.travel/docs/guides/consume-the-api.md)
>
> Read the full record behind an event.

> [card] [Events and durable execution](https://voyant.travel/docs/platform/fundamentals/events.md)
>
> How events work inside Voyant.


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