Developer docs menu
Building
Webhooks
Be told when something happens in a business: a booking, a payment, a review.
A webhook endpoint is an address of yours that the business’s events are sent to, however the booking was made: the booking form, the dashboard or the API.
Adding an endpoint
The owner adds one in the dashboard under Settings, AI agents & API. Software can add one with a key that has the manage:webhooks scope: POST /account/webhooks. A business can have up to 5. The address must be public https: private, loopback and internal addresses are refused. The signing secret is shown once, when the endpoint is made.
Events
| Event | When |
|---|---|
| booking.created | A booking is made. |
| booking.confirmed | A booking is confirmed. |
| booking.rescheduled | A booking is moved to a new time. |
| booking.started | The work has started. |
| booking.completed | The work is done. |
| booking.cancelled | A booking is cancelled. |
| booking.no_show | The customer did not turn up. |
| quote.created | A quote is written. |
| quote.sent | A quote is emailed to its customer. |
| lead.captured | Someone left their details without booking. |
| payment.received | A payment is taken. |
| payment.refunded | A payment is refunded. |
| review.created | A customer leaves a review. |
An endpoint asks for the events it wants, or * for all of them.
A delivery
Each delivery is a POST with a JSON body:
{
"id": "…",
"event": "booking.created",
"createdAt": "2026-12-01T09:00:00.000Z",
"businessId": "…",
"data": { … }
}| Header | What it holds |
|---|---|
| X-BookingMachine-Event | The event name. |
| X-BookingMachine-Delivery | This delivery’s id. The same on every retry, so use it to ignore one you have already handled. |
| X-BookingMachine-Attempt | Which attempt this is, from 1. |
| X-BookingMachine-Timestamp | When it was signed, in unix seconds. |
| X-BookingMachine-Signature | sha256= followed by the signature. |
Checking the signature
The signature is the hex HMAC-SHA256 of the timestamp, a full stop and the raw body, under the endpoint’s secret. Work it out from the bytes you received, before parsing them, and compare in constant time. Refuse a delivery whose timestamp is more than a few minutes old.
import { createHmac, timingSafeEqual } from 'node:crypto'
function isFromBookingMachine(secret, headers, rawBody) {
const timestamp = headers['x-bookingmachine-timestamp']
const given = headers['x-bookingmachine-signature'] ?? ''
const expected = 'sha256=' + createHmac('sha256', secret).update(timestamp + '.' + rawBody).digest('hex')
const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300
return fresh && given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected))
}Answering, and retries
Answer with any 2xx status within a few seconds, and do slow work afterwards. Anything else is tried again: 6 attempts in all, with a growing wait, over about nine hours. Redirects are not followed.
What the events carry
Booking, quote and lead events carry the customer’s name, email and phone. Treat what you receive as personal data, and keep the signing secret as you would a password.
Still have questions? Contact support