Webhooks & callbacks

The relays don’t just receive your calls: they call you back to deliver events (a ticket created, a message received, an approval completed…). These callbacks use the same HMAC signature as your outbound calls — but this time, you are the verifier.

The callback model

1. An event occurs on the relay side.
2. The relay makes a signed HTTP request to a URL on your backend (configured at provisioning via callback_url_base).
3. The request carries the X-Bloonio-Tenant-Id, X-Bloonio-Timestamp, and X-Bloonio-Signature headers, computed exactly as in Authentication (HMAC).
4. Your endpoint recomputes the signature with your tenant_secret and compares it before processing the event.

Verify before processing

Never act on an unverified callback. Recompute the signature from the raw bytes of the received body and compare in constant time. Reject (401) any missing, out-of-window, or invalid signature.

Verifying an inbound signature

The recipe is the inverse of sending: take the raw body bytes, compute sha256_hex(body), rebuild "{timestamp}.{body_hash}", sign it with your tenant_secret, then compare to the received header. The code from Authentication (HMAC) is reusable as-is for verification.

Best practices

• Idempotency. An event may be delivered more than once. Derive an idempotency key (event id) and ignore duplicates.
• Respond fast. Acknowledge (2xx) quickly, then process in the background; slow handlers trigger retries.
• Time window. Apply the same timestamp tolerance (~30s) as the relay.

Per relay

• Chat Relay — emits a family of events (conversation, message, ticket, escalation, operator) to /api/v1/chat-callbacks/*, and the Python SDK provides an adapter that mounts and verifies those routes for you. Full catalog: Webhook callbacks — Chat Relay.
• Auth Relay — authentication results arrive mostly as device push and security alerts, not classic HTTP webhooks. See Push & security alerts.

Next steps

• Authentication (HMAC) — the signing recipe, reusable for verification.
• Webhook callbacks — Chat Relay — the event list.