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:

HeaderValue
BookMyBays-Event-IdThe event’s id (same as id in the body)
BookMyBays-Event-Typee.g. booking.confirmed
BookMyBays-Delivery-IdThis delivery’s id (not sent on test events). Quote it to support
BookMyBays-Signaturet=<unix seconds>,v1=<hex signature>
User-AgentBookMyBays-Webhooks/1.0

Verifying the signature

  1. Split the BookMyBays-Signature header on , to get t and v1.
  2. Build the string <t>.<raw request body>. Use the body exactly as received, before any JSON parsing.
  3. Compute an HMAC-SHA256 of that string, using the whole signing secret (including whsec_) as the key. Hex-encode the result.
  4. Compare it with v1 using a constant-time comparison. Reject the message if they differ.
  5. Reject it if t is more than 5 minutes from the current time, to stop replays. t is 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.confirmed can land after that booking’s booking.updated. Compare data.updatedAt and 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
}
  • marketingConsent is the customer’s current permission: they agreed, and haven’t unsubscribed since. Only email marketing to customers where it is true. When a customer unsubscribes, a customer.updated arrives with marketingConsent: false and marketingOptedOut: true.
  • previousEmail appears on customer.updated only, and is set when the email address changed. Use it to find the existing contact.
  • source is "prelaunch" for customers who signed up before the venue opened, otherwise null.
  • A customer can be created when they start a checkout, so customer.created can 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" }
}
  • timezone is the venue’s, for display.
  • source is how the booking was made: online, walk_in, phone, agent, admin or coach.
  • 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 with groupLead: true; the others show 0. groupLead is null for ordinary bookings.
  • Extra time bought during a session arrives as its own booking.confirmed, with extendsBookingId set to the original booking.
  • booking.updated, booking.cancelled, booking.checked_in and booking.no_show are 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.