Webhook developer guide

Booking Terminal sends webhooks as signed HTTP POST requests when bookings are created, updated, or canceled. This guide covers everything you need to receive, verify, and process them.

Setup

The account owner creates the webhook endpoint in the Booking Terminal dashboard (Settings → Webhooks), entering your URL and choosing which event types to send — there's a step-by-step in the operator guide. You need two things from them: the endpoint URL they registered must be one you control, served over HTTPS and reachable from the public internet (requests to private or internal network addresses are refused, so localhost won't work — use a tunnel during development), and the signing secret, a 64-character hex string shown once when the endpoint is created. There is no way to retrieve the secret again or rotate it in place; if it's lost or compromised, delete the endpoint and create a new one.

Events

There are three event types:

There is no wildcard or catch-all event type. To receive everything, subscribe the endpoint to all three. (Zapier's "New, Updated, or Canceled Booking" trigger is exactly that — a subscription to all three.)

One user action can emit several events. Rebooking is the main example: the original booking emits booking.cancelled and booking.updated, and the replacement booking emits booking.created. Each event is delivered separately.

Payloads

Every event has the same envelope and the same data shape — a full snapshot of the booking at the time of the event, not a partial diff. A booking.updated event looks like this:

{
  "id": "1f0c2a7e-9d34-4c8b-b1a2-6f5e8d9c0b3a",
  "type": "booking.updated",
  "apiVersion": "2025-06-04",
  "created": "2026-06-12T15:04:05Z",
  "dashboardId": "8a23c917-55d1-4f6e-9b0c-2d4e6f8a0c1e",
  "data": {
    "id": "3b9d6c1f-2e80-47ab-8f3d-9c5b7a1e4d2f",
    "number": 1042,
    "codedNumber": "QK7M2",
    "customer": {
      "id": "7c4e2f9a-1b3d-48c6-a5e7-0f2d4b6c8e1a",
      "fullName": "Dana Rivera",
      "email": "dana@example.com",
      "phoneNumber": "5551234567",
      "phoneCountryCode": "+1",
      "stripeCustomerId": "cus_QxT3aBcDeFgHiJ",
      "marketingEmailConsent": true
    },
    "availability": {
      "id": "5d8f3a2c-6e90-41b7-9c4a-8b1e3f5d7a9c",
      "name": "Sunset Kayak Tour",
      "start": "2026-06-20T22:00:00Z",
      "end": "2026-06-21T00:00:00Z",
      "bookable": {
        "id": "2a6c8e0f-4b9d-43e1-a7c5-9f1b3d5e7a0c",
        "name": "Sunset Kayak Tour",
        "sku": "KAYAK-SUNSET",
        "code": "SKT"
      }
    },
    "createdAt": "2026-06-10T13:22:48Z",
    "selections": [
      {
        "id": "9e1b3d5f-7a2c-46e8-b0d4-6c8a0e2f4b6d",
        "priceOption": {
          "id": "4f8a0c2e-6b1d-49f3-8e5a-1c3b5d7f9a2c",
          "sku": "ADULT",
          "name": "Adult"
        },
        "customFieldAnswers": []
      }
    ],
    "rebookedTo": null,
    "rebookedFrom": null,
    "customFieldAnswers": [
      {
        "id": "6c0e2a4f-8d3b-41c7-9f5e-3a7b9d1f5c8e",
        "name": "How did you hear about us?",
        "displayValue": "Instagram"
      }
    ],
    "bookingTotal": 15000,
    "netPaid": 15000,
    "remainingDue": 0,
    "note": "",
    "status": "confirmed",
    "signedWaivers": [
      {
        "id": "0b4d6f8a-2c5e-47a9-b1d3-5f7a9c1e3b6d",
        "signerFirstName": "Dana",
        "signerLastName": "Rivera",
        "signerEmail": "dana@example.com",
        "signerDob": "1990-04-17",
        "signerPhone": "5551234567",
        "signerZip": "11211",
        "marketingConsent": true,
        "signedAt": "2026-06-11T18:45:12Z",
        "isParticipant": true,
        "minorCount": 1
      }
    ]
  },
  "previousAttributes": {
    "netPaid": 7500,
    "remainingDue": 7500
  }
}

booking.created and booking.cancelled payloads are identical except that previousAttributes is never included and type differs.

Envelope fields

data (booking) fields

All keys are always present. Fields whose value can be null are noted; everything else uses an empty string, 0, false, or [] when there's nothing to report.

Nested objects

previousAttributes

On booking.updated, previousAttributes holds the previous values of the fields that changed, using the same keys and shapes as data:

• Nested objects contain only the keys that changed (e.g. {"customer": {"email": "old@example.com"}}).
• Arrays are all-or-nothing: if anything inside an array changed, the entire previous array is included.
• A value of null means the field was previously null (e.g. {"rebookedTo": null} on the booking that was just rebooked).
• If nothing observable changed, previousAttributes is an empty object ({}).

Verifying signatures

Every request carries these headers:

The signature is HMAC-SHA256, hex-encoded, computed with your signing secret (as an ASCII string) over the string {timestamp}.{raw request body} — the Unix timestamp from t=, a literal dot, then the exact bytes of the body. Each delivery attempt is signed freshly at send time, so you can safely reject stale timestamps (a tolerance of 5 minutes is reasonable) to prevent replays.

Delivery behavior

• Deliveries are HTTP POST requests with a JSON body.
• Success is any 2xx response. Anything else — including redirects, which we do not follow — counts as a failure. Respond within 15 seconds or the attempt times out.
• Failed deliveries are retried automatically with increasing delays for roughly a day before being marked failed. Don't build against a specific retry count or schedule — it may change.
• Return 2xx as fast as possible and do your real work asynchronously (queue the payload, then process). Slow handlers risk timing out and being redelivered.
• Endpoints must be HTTPS, and we refuse to deliver to private or internal network addresses — use a tunnel (e.g. ngrok) to test locally.
• Every delivery attempt, including the response status and a truncated response body, is visible in the dashboard under Settings → Webhooks → your endpoint, which is the fastest way to debug a failing receiver.