A webhook posts what happens at the business to an address you give: a booking made, an order placed, a sale refunded, a client archived. Zapier, Make or your own server takes it from there. Webhooks are under Settings, Connections, Webhooks and Zapier; a program with an API key can add its own, and an app from the marketplace adds the ones it needs.
Add a webhook
- Under Webhooks and Zapier, choose Add a webhook.
- Say What it is for, and paste The address to post to: it starts with https://. In Zapier or Make, start a Zap or a scenario with "Webhooks: Catch hook" and paste the address it gives you.
- Under Send, keep Everything it may read, or pick the events it gets.
- Choose Add it, and copy its signing secret: it is shown this once.
Send a sample posts a test event to it and says what the address answered.
What each delivery carries
Each event is posted as JSON: its id (such as evt_1042), its type (such as sale.refunded), when it happened, the business, the client it is about, and its data as the API gives it. A webhook hears only what it may read, judged as each delivery goes: one made in the app hears the parts the person who made it could read then, within their switches now; one made by a key hears what that key was given, within its maker's switches; and one made by a key that is turned off, paused or run out hears nothing. An event about a part it may not read is not sent to it, and the client is left out of an event for a webhook that may not read clients. When a client is erased for a privacy request, its event carries the client's id and nothing else, so a copy kept elsewhere can be erased too. A business keeping health information sends no client's notes and no answers on a form.
Each post carries an X-Booking-Signature header: t= the time, and v1= the HMAC-SHA256 of the time, a dot and the body, under the webhook's secret. X-Booking-Delivery names the delivery, the same each time it is tried, and X-Booking-Attempt says which try it is. Zapier does not need either.
In order, and tried again for 72 hours
Every event a webhook that is on is subscribed to is kept as a delivery the moment it happens, in the same step as the change itself, so nothing is lost when an address is down. A webhook gets its events in the order they happened, one at a time. An address that answers with a 2xx within 8 seconds has it; anything else is a failure, and the delivery is tried again after a minute, then 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and then once a day, until 72 hours after its first try. The webhook's later events wait behind it, so they never arrive out of order. After 72 hours it is given up on, kept on the webhook's list as Failed, and the next event goes.
A delivery can arrive more than once (an address that took it but answered too slowly is sent it again), so use the X-Booking-Delivery header, or the event's id, to take each one once. That is the whole promise: at least once, in order for each webhook, for 72 hours.
The record of deliveries, and Send Again
Each webhook says how it stands: On; On, failing with since when; Switched off: failing; Off with its app while its app is paused; or Off. Beside it are the deliveries waiting and the ones that failed. Deliveries opens its record, the newest first, for 90 days: each event, when it happened, how many times it was tried, the address's last answer or why it did not go, and when it is tried next. What a delivery carried is never shown, and is let go once it is delivered or given up on.
Send again sends a failed delivery once more, from its first try and in its place among the webhook's events, with what the event and the webhook may read now. Send every failed one again does that for the latest 500 at once. A delivery that was never sent, because the webhook may not read it or what it was about is gone, is not sent again.
Switched off after three days
A webhook whose address has not taken a delivery for three days is switched off, and every owner is emailed with its name and since when it has been failing. What was waiting for it is kept, and nothing new is kept or sent for it while it is off. Once the address answers again, choose Turn it on again: what waited goes out in order, and the failed ones can then be sent again from Deliveries. A webhook turned off by a person is the same. A webhook removed lets go of what waited for it, and its record is kept.
When the person who made it leaves
A webhook acts for the person who made it. One made in the app hears nothing while their login is paused, and nothing once they are taken off the team, until an owner chooses Take it over on its row: it then hears what it heard before, as the owner's. One made by a key or an app goes with its key, which an owner takes over or makes again (see When the person who made a key or a link leaves). What happened while it heard nothing is not sent to it.
For developers
A program does the same through the API with its key: list a webhook's deliveries, send one again, send every failed one again, and turn a webhook on again (see Connections and the API). The API reference at /developers lists every event and what each carries.
Best practices
- Answer with a 2xx as soon as the post arrives, and do the work after: an address that takes longer than 8 seconds is a failure, and the event comes again.
- Check X-Booking-Signature with the secret before trusting a post, and take each delivery once by its X-Booking-Delivery header.
- Give each webhook only the events it needs, and remove a webhook the day nothing reads it any more.
- When an owner is emailed that a webhook was switched off, fix the address first, then turn it on again and send the failed ones again.