Skip to content

Handling Webhook Events API (1.5.0)

Webhook API specification for receiving real-time notifications from The Bookings Group system. Distributors must implement this endpoint to receive notifications about booking updates and inbound messages from operators via their Table Management System (TMS).

Event Types

eventTypeDescriptionPopulated fields
booking.updatedA booking was created, updated, or cancelledbookings
message.receivedOne or more operator messages were sent for a bookingmessages

Authentication

Every request includes an X-API-Key header containing an HMAC-SHA256 hex digest of the raw request body, signed with your API key. Verify this signature before processing the payload:

expected = HMAC-SHA256(key=YOUR_API_KEY, message=raw_request_body).hex()
assert request.headers["X-API-Key"] == expected

Response Codes

Return 204 No Content on success. Any non-2xx response causes the delivery to be considered failed. Respond within 30 seconds to avoid a timeout.

Download OpenAPI description
BookableWebhookApi.json
BookableWebhookApi.yaml
Overview
URL
https://www.bookabletech.com
Bookable
hello@bookabletech.com
License
Proprietary
Languages
Servers
Distributor webhook endpoint
https://your-distributor-domain.com

Receive booking and messaging notifications

Request

Endpoint that distributors must implement to receive notifications. The Bookings Group system sends HTTP POST requests to this endpoint when:

  • A booking is updated (booking.updated)
  • An operator sends a message via their TMS (message.received)

Use eventType to determine which top-level field (bookings or messages) is populated.

Security
apiKey
Bodyapplication/jsonrequired
eventTypestringrequired

Type of event that triggered the notification

Enum"booking.updated""message.received"
Example: "booking.updated"
timestampstring(date-time)required

ISO 8601 timestamp when the event was dispatched

Example: "2025-06-17T10:30:00Z"
bookingsArray of objects or null(Booking)

Booking data. Present when eventType is booking.updated, null otherwise.

messagesArray of objects or null(MessagePayload)

Message data. Present when eventType is message.received, null otherwise. All messages in a single notification belong to the same booking.

curl -i -X POST \
  https://your-distributor-domain.com/ \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "eventType": "booking.updated",
    "timestamp": "2025-06-17T11:45:00Z",
    "bookings": [
      {
        "id": "29|X9|275cc44dd2e2496fba44857c9257443a|B",
        "compositeId": "29|X9|275cc44dd2e2496fba44857c9257443a|d99128c546b34b619c4477b712869f2b",
        "date": "2025-06-25",
        "time": "21:30:00",
        "partySize": 6,
        "status": "confirmed",
        "reference": "REF-20250617-001",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "phone": "+1234567890",
        "company": null,
        "location": null,
        "duration": 120,
        "productName": "dinner",
        "productType": "dinner",
        "notes": "Anniversary dinner — window table if possible",
        "source": "MyDistributor",
        "createdDate": "2025-06-17T09:15:00Z",
        "lastUpdate": "2025-06-17T11:45:00Z",
        "preorders": [],
        "preorderMenus": []
      }
    ],
    "messages": null
  }'

Responses

Notification received and processed successfully

Response
No content