Developer guide
How to receive BookMyBays webhooks
Venues can send customer and booking changes to their own systems as they happen. This guide is for whoever builds the receiving end. If you’re connecting a CRM through Zapier, Make or n8n, you don’t need most of this: their webhook step handles the request for you.
The venue owner sets up a webhook in Settings → Integrations → Webhooks and gets a signing secret, shown once. Ask them for it.
The request
We send a POST to the URL with Content-Type: application/json; charset=utf-8 and these headers:
| Header | Value |
|---|---|
| BookMyBays-Event-Id | The event’s id (same as id in the body) |
| BookMyBays-Event-Type | e.g. booking.confirmed |
| BookMyBays-Delivery-Id | This delivery’s id (not sent on test events). Quote it to support |
| BookMyBays-Signature | t=<unix seconds>,v1=<hex signature> |
| User-Agent | BookMyBays-Webhooks/1.0 |
Verifying the signature
- Split the
BookMyBays-Signatureheader on,to gettandv1. - Build the string
<t>.<raw request body>. Use the body exactly as received, before any JSON parsing. - Compute an HMAC-SHA256 of that string, using the whole signing secret (including
whsec_) as the key. Hex-encode the result. - Compare it with
v1using a constant-time comparison. Reject the message if they differ. - Reject it if
tis more than 5 minutes from the current time, to stop replays.tis refreshed on every retry, so retried messages still pass.
Example in Node.js
import crypto from 'node:crypto';
// rawBody: the request body exactly as received, before JSON parsing.
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = crypto
.createHmac('sha256', secret) // the whole secret, including "whsec_"
.update(`${parts.t}.${rawBody}`)
.digest('hex');
const a = Buffer.from(expected, 'hex');
const b = Buffer.from(parts.v1 ?? '', 'hex');
return a.length === b.length && crypto.timingSafeEqual(a, b);
}Responding
- Reply with any 2xx within 10 seconds. Anything else is a failure: other statuses, timeouts and connection errors.
- Redirects are not followed. Use the final URL.
- Do slow work after replying, not before.
Retries, duplicates and order
- A failed message is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 10 hours. That’s 8 attempts over about 27 hours, after which we give up on that event.
- If a URL keeps failing for 24 hours, we switch the webhook off. The venue sees why in their settings.
- Messages can arrive more than once. De-duplicate on the event
id. - Messages can arrive out of order. For example, a retried
booking.confirmedcan land after that booking’sbooking.updated. Comparedata.updatedAtand ignore anything older than what you already have.
Event body
Every event has the same envelope:
{
"id": "0b6e1d0c-5a8f-4a43-9b6e-2c8a4f1f7f10",
"type": "booking.confirmed",
"apiVersion": "2026-11-20",
"createdAt": "2026-11-20T18:02:11.482Z",
"venueId": "7d9a…",
"data": { }
}Times are UTC. Money is in minor units (pence or cents) of currency, which is always present and uppercase.
Customer events
customer.created and customer.updated
"data": {
"id": "c1f2…",
"email": "[email protected]",
"firstName": "Ann",
"lastName": "Lee",
"phone": "07700 900123",
"marketingConsent": true,
"marketingOptedOut": false,
"source": null,
"totalBookings": 4,
"totalSpentInPence": 12000,
"currency": "GBP",
"lastVisitedAt": "2026-11-12T19:00:00Z",
"createdAt": "2026-03-01T10:15:00Z",
"updatedAt": "2026-11-20T18:02:11Z",
"previousEmail": null
}marketingConsentis the customer’s current permission: they agreed, and haven’t unsubscribed since. Only email marketing to customers where it istrue. When a customer unsubscribes, acustomer.updatedarrives withmarketingConsent: falseandmarketingOptedOut: true.previousEmailappears oncustomer.updatedonly, and is set when the email address changed. Use it to find the existing contact.sourceis"prelaunch"for customers who signed up before the venue opened, otherwisenull.- A customer can be created when they start a checkout, so
customer.createdcan arrive for someone who never finishes booking.
customer.deleted
"data": { "id": "c1f2…", "email": "[email protected]", "mergedIntoCustomerId": null }When two customers were merged, mergedIntoCustomerId is the one that remains, and a customer.updated for that customer follows. Otherwise the customer was deleted. See Deleting customer data.
Booking events
booking.confirmed, booking.updated, booking.cancelled, booking.checked_in and booking.no_show all carry the booking:
"data": {
"id": "b9e4…",
"reference": "CG-2026-1042",
"status": "confirmed",
"startTime": "2026-11-28T18:00:00Z",
"endTime": "2026-11-28T19:00:00Z",
"durationMinutes": 60,
"timezone": "Europe/London",
"bay": { "id": "…", "name": "Bay 3" },
"sessionType": { "id": "…", "name": "Standard session" },
"players": { "total": 3, "adults": 2, "students": 0, "juniors": 1, "seniors": 0 },
"amountInPence": 4500,
"amountPaidInPence": 4500,
"currency": "GBP",
"source": "online",
"promoCode": null,
"walkUp": false,
"groupBookingId": null,
"groupLead": null,
"extendsBookingId": null,
"checkedInAt": null,
"cancelledAt": null,
"cancellationReason": null,
"createdAt": "2026-11-20T18:01:40Z",
"updatedAt": "2026-11-20T18:02:11Z",
"customer": { "id": "c1f2…", "name": "Ann Lee", "email": "[email protected]", "phone": "07700 900123" }
}timezoneis the venue’s, for display.sourceis how the booking was made:online,walk_in,phone,agent,adminorcoach.- Group bookings (one party across several bays) send one event per bay, all sharing the same
groupBookingId. The price and headcount are on the row withgroupLead: true; the others show 0.groupLeadisnullfor ordinary bookings. - Extra time bought during a session arrives as its own
booking.confirmed, withextendsBookingIdset to the original booking. booking.updated,booking.cancelled,booking.checked_inandbooking.no_showare only sent for bookings that were confirmed first. Abandoned checkouts are never sent.
Deleting customer data
Venues handle erasure requests by deleting the customer, which sends customer.deleted with no mergedIntoCustomerId. When you get one, delete the contact, and remove any booking events you stored for them too, since those also contain the customer’s name and email.
Testing your receiver
The venue can press Send test event on the webhook at any time, even while it’s switched off. It sends a webhook.test event straight away and shows the result. Every delivery, with the exact body we sent, is in the webhook’s delivery log for 30 days.