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

EventWhen
booking.createdA booking is made.
booking.confirmedA booking is confirmed.
booking.rescheduledA booking is moved to a new time.
booking.startedThe work has started.
booking.completedThe work is done.
booking.cancelledA booking is cancelled.
booking.no_showThe customer did not turn up.
quote.createdA quote is written.
quote.sentA quote is emailed to its customer.
lead.capturedSomeone left their details without booking.
payment.receivedA payment is taken.
payment.refundedA payment is refunded.
review.createdA 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": { … }
}
HeaderWhat it holds
X-BookingMachine-EventThe event name.
X-BookingMachine-DeliveryThis delivery’s id. The same on every retry, so use it to ignore one you have already handled.
X-BookingMachine-AttemptWhich attempt this is, from 1.
X-BookingMachine-TimestampWhen it was signed, in unix seconds.
X-BookingMachine-Signaturesha256= 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.

Note: An endpoint that has done nothing but fail for a day is turned off. The owner can turn it on again in the dashboard.

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.