Set up webhooks for booking events

In breve

Webhooks tell your system when something happens to a booking you made through the API, without you having to ask. You add them in the Webhooks panel on the developer dashboard.

Events

- booking.created - booking.confirmed - booking.cancelled

Booking events come from stored bookings, so bookings made with test keys do not send them. Use a test event to check your endpoint instead.

Add a webhook

1. Enter the Endpoint address. It must be a public https:// address; addresses inside private networks are refused. 2. Under Events, tick at least one event. 3. Choose Add webhook. 4. Copy the signing secret (it starts with whsec_). We only show it once.

You can have up to 5 webhook endpoints.

Check the signature

Every delivery has an X-Rally-Signature header like t=1767225600,v1=.... To check it, take the time (t), add a full stop and the raw request body, and work out the HMAC-SHA256 of that text with your signing secret. It should match v1. Reject any request where it does not.

Test your endpoint

Choose Send test event. We send a ping event, and it appears in the Delivery log once it has been sent.

Retries and the delivery log

Answer with any 2xx status within 10 seconds. Anything else counts as a failure and we try again after about 1, 5 and 30 minutes, then 2 hours: five attempts in all. The Delivery log shows each delivery as Queued, Retrying, Delivered or Failed, with the number of attempts.

Webhooks are a convenience, not a guarantee, so check important bookings with the API too.

Remove a webhook

Choose the bin icon next to it and confirm. Deliveries to it stop straight away.