Webhooks & events

Private beta

The event contract below is the committed design for Journeys webhooks, being rolled out with private beta tenants. Event names, payload shapes, and delivery semantics documented here are the contract implementations should build against. Confirm activation for your tenant with your implementation team.

Polling works for a booking flow the guest is driving, but operational surfaces — a sales workbench, a CRM timeline, an agent dashboard, downstream fulfilment — need to know when things happen. Journeys emits webhooks for the commerce events that matter.

Subscribing

Webhook endpoints are configured per tenant in journey.yaml:

webhooks:
  - url: https://workbench.example.com/hooks/journeys
    events:
      - booking.created
      - payment_request.completed
    secret: vault::journeys_webhook_secret

Multiple subscriptions are supported (e.g. one for the workbench, one for analytics), each with its own event filter and signing secret. Secrets are stored in the Edge vault, never in configuration files.

Events

Event	Fired when	Payload
basket.created	A commerce session starts	Basket summary (id, tenant, channel, package, departure, occupancy)
basket.updated	Selections, travellers, or promotions change	Basket summary + changed fields
basket.expired	The 15-minute basket expiry lapses without booking	Basket summary — useful for abandonment recovery
payment_request.created	A payment request is issued	Payment request (id, basket, amount, currency, status)
payment_request.completed	A payment is confirmed	Payment request with status: completed
payment_request.failed	A payment attempt fails	Payment request with status: failed
booking.created	Checkout lands as a Salesforce itinerary	itinerary_id, booking_reference, basket summary

Delivery

Each delivery is an HTTPS POST:

{
  "id": "evt_9f2c1e0a",
  "type": "booking.created",
  "tenant_id": "meridian",
  "created_at": "2027-06-01T10:05:00Z",
  "data": {
    "itinerary_id": "a0R0000000000AAAA",
    "booking_reference": "MER-104233",
    "basket_id": "1f2e3d4c-0000-0000-0000-000000000000"
  }
}

Semantics	Behaviour
Signing	X-Journeys-Signature header — HMAC-SHA256 of the raw body using the subscription secret. Verify before trusting.
Ordering	Best-effort per basket; consumers must treat id as the deduplication key and tolerate out-of-order delivery.
Retries	Non-2xx responses are retried with exponential backoff for up to 24 hours.
At-least-once	Deliveries can repeat — handlers must be idempotent on event id.
Timeout	Respond 2xx within 10 seconds; do processing asynchronously.

Workbench pattern

For a single-view sales workbench the useful combination is:

1. Drive the booking flow through the Journeys API (or embed the hosted UI).
2. Subscribe the workbench backend to booking.created and payment_request.completed to update the timeline in real time.
3. Use Edge Composite for any Salesforce context the workbench needs around the event (itinerary detail, account history) — one composite call per event, no polling loops.