Webhook Guide

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

The Bookable webhook system delivers real-time notifications to your endpoint when booking events occur — such as new bookings, updates, and cancellations.

Integration flow

1. Register your callback URL via the API and receive a secretKey
2. Store the secret key securely — you'll use it to verify every incoming request
3. Implement an HTTPS endpoint that accepts POST requests and verifies the HMAC-SHA256 signature
4. Respond with 204 No Content on success

Step 1: Register your webhook

Obtain an access token

See Authentication for the full token flow. Quick reference:

curl -X POST https://auth.bookabletech.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "api.bookabletech.com"
  }'

Register your callback URL

curl -X POST https://api.bookabletech.com/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUrl": "https://your-domain.com/webhooks/booking-notification"
  }'

Response:

{
  "secretKey": "123e4567-e89b-12d3-a456-426655440000",
  "callbackUrl": "https://your-domain.com/webhooks/booking-notification"
}

Update your callback URL

curl -X PUT https://api.bookabletech.com/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUrl": "https://your-new-domain.com/webhooks/booking-notification"
  }'

Delete your webhook

curl -X DELETE https://api.bookabletech.com/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Step 2: Implement your webhook endpoint

Your endpoint must accept POST requests, verify the HMAC-SHA256 signature, process the event, and respond with 204 No Content.

Supported event types

Full endpoint implementation

// Node.js / Express
const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.BOOKABLE_WEBHOOK_SECRET;

app.post('/webhooks/booking-notification', (req, res) => {
  try {
    if (!verifySignature(req.headers['x-api-key'], req.body, WEBHOOK_SECRET)) {
      return res.status(401).json({ success: false, error: 'unauthorized' });
    }

    const { eventType, timestamp, booking } = req.body;

    if (!eventType || !timestamp) {
      return res.status(400).json({ success: false, error: 'validation_error' });
    }

    switch (eventType) {
      case 'booking.created':
      case 'booking.updated':
      case 'booking.cancelled':
        console.log(`Event: ${eventType}, booking ID: ${booking[0]?.id}`);
        // Handle event...
        break;
      default:
        console.warn(`Unknown event type: ${eventType}`);
    }

    res.status(204).end();

  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).json({ success: false, error: 'internal_error' });
  }
});

function verifySignature(signature, body, secret) {
  if (!signature) return false;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(body))
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

Webhook payload

{
  "eventType": "booking.created",
  "timestamp": "2025-06-17T10:30:00Z",
  "booking": [
    {
      "id": "12345678-1234-1234-1234-123456789012",
      "venueId": "87654321-4321-4321-4321-210987654321",
      "date": "2025-06-25",
      "time": "19:30:00",
      "partySize": 4,
      "status": "confirmed",
      "reference": "REF-20250617-001",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "duration": 120,
      "notes": "Window table preferred",
      "createdDate": "2025-06-17T09:15:00Z",
      "lastUpdate": "2025-06-17T10:30:00Z"
    }
  ]
}

Booking status values

Signature verification

Every webhook request includes an X-API-Key header containing an HMAC-SHA256 hex digest of the raw request body, signed with your secretKey.

Verification steps:

1. Read the raw request body as a string (before any JSON parsing)
2. Compute HMAC-SHA256(secretKey, rawBody) and hex-encode it
3. Compare the result to the X-API-Key header using a timing-safe comparison

Error handling & retries

Your endpoint should return appropriate HTTP status codes:

Failed deliveries are retried with exponential backoff: 1, 2, 4, 8, 16, and 32 minutes. After 6 attempts the event is dropped and logged for review.

Best practices

1. HTTPS only — never register an HTTP callback URL
2. Verify every request — always validate the signature before processing
3. Respond quickly — return 204 immediately and process the event asynchronously if needed
4. Handle duplicates — retries can deliver the same event more than once; make your handler idempotent
5. Log everything — store raw payloads for debugging and auditing

Troubleshooting

Support: hello@bookabletech.com