Register to Webhook Events API (2.0.0)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Receiving events

Once a callback URL is registered, Bookable POSTs a JSON BookingNotification to it for each event. Delivery is at-least-once: the same event may be delivered more than once, so consumers must be idempotent (booking events by booking id, messages by message id).

Each request carries an X-API-Key header containing a lowercase hex HMAC-SHA256 signature of the raw request body, keyed with the secretKey of the subscription it was sent for. Verify it by recomputing the HMAC over the received body and comparing.

It also carries an X-Webhook-Id header naming that subscription. If you hold more than one subscription, use it to pick the right secretKey rather than inferring it from the URL the request arrived on. A single-subscription integration can ignore the header.

Answer within 10 seconds. Timeouts, retries and redelivery per event type are described in the Handling Webhook Events API.

Subscriptions

A distributor may register several webhook subscriptions, each with its own callback URL, secret and event filter — see /webhooks/subscriptions. This lets an application acting on your behalf subscribe without disturbing your own integration.

A distributor may hold up to 10 subscriptions, paused ones included; creating an 11th answers 409 with code WHK-N-004. Subscriptions belong to one environment: one created in the sandbox does not exist in Live, and the reverse.

Event types (eventType):

• booking.updated — a booking was created or changed (payload in bookings).
• message.received — one or more messages for a booking (payload in messages). Emitted only for operator_to_partner messages (the venue operator sent it, delivered to the partner); filter on subject/senderEmail.
• venue.updated — a venue you distribute changed status; today only closures are sent (payload in venues).
• webhook.ping — a connectivity test you asked for with POST /webhooks/test; no payload. Test deliveries also carry an X-Webhook-Test: true header.

Switch on eventType and answer 2xx to types you do not handle: new ones are added over time.

Testing

POST /webhooks/test sends a test event to your subscriptions and reports what each endpoint answered. In Live it sends webhook.ping; in the sandbox it also sends sample, real and simulated business events.

Changes in 2.0.0

• The singleton operations GET, POST, PUT and DELETE /webhooks, deprecated since 1.6.0, are removed. Use /webhooks/subscriptions.
• POST /webhooks/test is redefined — see that operation.
• BookingNotification documents venue.updated (with venues) and webhook.ping.