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.
What Voyant sends
Each delivery is aPOST request with a JSON body:
Events carry IDs and short facts, not whole records. To get the full record, read it from the Admin API.
These headers come with each delivery:
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, includingwhsec_.
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 any2xx status within 15 seconds. Voyant follows up to 3 redirects.
- Number of retries: 5 by default and 10 at most. The admin form uses the default. To set another number, send
maxRetriesto the Admin 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.
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, storex-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
Products, prices, and availability
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.
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
Inquiries
Marketing consent
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:
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 reachescontact_completed on a product booking, so your ad platforms can count it as a lead. It pushes this to the data layer:
- 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.
engine.contact.submitted and requires ad storage consent, with this image URL:
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 sendscatalog.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 sendscatalog.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.
basissays which applied:consentorlegitimate_interest_measurement. A customer whose consent is on record is always sent asconsent. Uselegitimate_interest_measurementevents for conversion reporting only: never add their hashes to an ad platform audience. -
Whose contact.
matchhashes 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, andsourceType(how the booking was made, for examplemanual). 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 thatcatalog.booking.conversionreports never also sends this event. A booking made through the booking engine never sends it either: the engine and your website measure those.
Hashed contact for ad matching
These five events can carry amatch object, so your ad platforms can match a lead or a booking to the person who clicked your ad:
emailSha256is the SHA-256 hash of the email, trimmed and lower-cased.phoneSha256is the SHA-256 hash of the phone as digits only, with the country code and without+or leading zeros (for example40712345678). A phone saved without a country code, such as0712 345 678or+0712 345 678, has nophoneSha256, 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:- 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
nextCursoruntil it isnull, 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 underhttps://{workspace}.onvoyant.com/api/v1/admin/webhooks. The token needs the webhooks permission: read, write, or delete. See Consume the API for tokens.
Next steps
Consume the API
Read the full record behind an event.
Events and durable execution
How events work inside Voyant.