Skip to main content
Use webhooks to stay in sync with booking and payment events.

​
1) Create a webhook subscription

curl -X POST "https://api.boseat.com/v1/webhooks/subscriptions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yourapp.com/webhooks/boseat",
    "events": ["booking.created", "booking.updated", "invoice.updated"],
    "secret": "<generate-a-strong-secret>"
  }'
Store the secret securely; you need it to verify signatures. Events (common):
  • booking.created, booking.updated, booking.cancelled
  • invoice.created, invoice.updated, invoice.paid, invoice.failed
  • payment.failed (if applicable)

​
2) Receive events

curl -X POST "https://api.yourapp.com/webhooks/boseat" \
  -H "Content-Type: application/json" \
  -H "Boseat-Signature: t=...,v1=..." \
  -d '{"type":"booking.created","data":{...}}'
Your endpoint should return 2xx quickly; handle work asynchronously.

​
3) Verify signatures

  • Compute an HMAC (SHA-256) using the shared secret and the raw request body.
  • Compare to the v1 hash in the Boseat-Signature header and reject mismatches.
  • Allow small clock skew (a few minutes) when validating timestamped signatures.

​
4) Retry behavior

  • Boseat retries failed deliveries with exponential backoff.
  • Ensure your handler is idempotent: use the event ID to de-duplicate.

​
5) Test locally

  • Use an HTTPS tunnel (e.g., ngrok) to expose your local server and validate signature handling.