Webhooks

Overview#

The Bokko webhook system sends real-time HTTP notifications when the status of a booking changes. This allows your system to respond immediately to events without having to constantly poll the API.

• Real-time: Notifications are sent at the moment a status change occurs.
• HTTPS: Webhooks can only be sent to secure endpoints.
• HMAC-SHA256 Signature: Every payload is cryptographically signed; you can verify its authenticity.

Configuration#

You can register the webhook URL at the PUT /v1/webhooks/config endpoint. This requires the webhook.manage capability.

curl -X PUT https://api.bokko.io/v1/webhooks/config \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/webhooks/bokko" }'

URL Requirements:

• HTTPS protocol is mandatory.
• Maximum 500 characters long.
• Must not contain authentication credentials (user:pass@).

Restricted Address Ranges:

Events#

Payload Format#

Every webhook delivery is a JSON object with the following structure:

<!-- doc-example: webhook-payload -->

{
  "event": "booking.confirmed",
  "deliveryId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-04-01T09:00:00.000Z",
  "salonSlug": "precision-cuts",
  "booking": {
    "bookingId": "abc123",
    "publicReference": "BK-A2B3C4D5",
    "status": "confirmed",
    "serviceId": "svc_haircut_01",
    "serviceName": "Haircut",
    "staffId": "staff_anna_01",
    "staffName": "Anna",
    "guestName": "Peter Smith",
    "requestedSlot": {
      "date": "2026-04-05",
      "startTime": "10:00",
      "timezone": "Europe/Budapest"
    },
    "confirmedSlot": {
      "date": "2026-04-05",
      "startTime": "10:00",
      "endTime": "10:45",
      "timezone": "Europe/Budapest"
    },
    "note": null,
    "createdAt": "2026-04-01T09:00:00Z",
    "updatedAt": "2026-04-01T09:15:00Z"
  }
}

The confirmedSlot contains the finalized appointment time, if such exists for the booking (e.g. in confirmed, completed or no_show status). For cancelled or declined bookings, this value is always null in the API payload, even if the booking was previously confirmed. This reflects that the time slot is no longer occupied.

Status Enum ↔ Event Name Mapping#

The booking status field uses a camelCase enum (Bokko Public API convention), while the webhook event names use a snake_case namespaced format (REST / event sourcing convention). They differ intentionally — clients should apply the following mapping:

HTTP Headers#

Every webhook request contains the following custom headers:

Signature Verification#

Node.js#

const crypto = require('crypto');

function verifySignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');

  const sig = signature.replace('sha256=', '');

  return crypto.timingSafeEqual(
    Buffer.from(sig, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

Python#

import hmac
import hashlib

def verify_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()

    sig = signature.replace('sha256=', '')

    return hmac.compare_digest(sig, expected)

Delivery Rules#

Possible outcomes:

• success — 2xx response code received
• timeout — endpoint did not respond within 8 seconds
• network_error — endpoint was not reachable
• http_error — non-2xx response code (e.g., 500)

Delivery Log#

You can review deliveries from the past 90 days at the GET /v1/webhooks/deliveries endpoint.

Filtering Options:

Pagination is cursor-based: provide the meta.cursor field from the response in the cursor parameter of the next request.

Secret Rotation#

If your secret is compromised, you can generate a new secret:

curl -X POST https://api.bokko.io/v1/webhooks/config/rotate-secret \
  -H "Authorization: Bearer {API_KEY}"

Best Practices#

1. Deduplicate based on deliveryId — although at-most-once is the guarantee, it is worth checking in case of network anomalies.
2. Respond quickly with 200, perform actual processing asynchronously — the 8-second timeout can be tight for complex logic.
3. Periodically reconcile with the GET /v1/bookings endpoint to ensure you don't miss any events.
4. For local development, use webhook.site or ngrok to receive webhooks.