Skip to main content

Overview

Webhooks let Sendora push events to your server the moment they happen, instead of polling the API. Register an HTTPS endpoint, choose which events you care about, and Sendora will deliver a signed POST request within seconds.

Event catalog

Registering an endpoint

Returns:
Save the secret immediately. It is sensitive and should not be committed or returned to your frontend.

Payload shape

Every webhook POST contains the event-specific fields plus the event_type field:
Every delivery also carries two request headers: X-Sendora-Delivery-Id (the delivery record ID, which stays the same across retries of one delivery, so use it to deduplicate) and X-Sendora-Event-Type (the same value as event_type in the body). The request body does not add a universal event ID or timestamp; do not assume those fields exist unless they are part of the event payload you receive.

Event-specific payloads

booked_via is either "voice_agent" (AI booked during a call) or "operator" (manual booking in Unibox).

Verifying signatures

Sendora signs every delivery with HMAC-SHA256 using the endpoint’s secret. Always verify the signature before processing the payload, and reject any delivery whose signature timestamp is more than 5 minutes old (the verifier below does both). Every retry is signed again with a fresh timestamp, so a retry hours later still passes the 5 minute check. Sendora signs every delivery with HMAC-SHA256. Always verify the signature on the raw request body before you process an event.
The signature arrives in the X-Sendora-Signature header as t=<unix seconds>,v1=<hex>. The signed text is the timestamp, a full stop, and the raw request body exactly as received, so verify before you parse the JSON. Reject a delivery whose signature does not match or whose timestamp is more than 5 minutes old. Here’s how to wire it into a request handler:
Never process a webhook payload without verifying the signature. Forged events are rejected as 401 on Sendora’s side, but your own endpoint must also verify.

Delivery flow

Delivery and retries

  • Sendora expects your endpoint to return 2xx within 10 seconds. A slower response counts as a failed attempt.
  • If an attempt times out or returns a non-2xx status, Sendora retries 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours after the previous failure. That is 6 attempts in total, over roughly 8 hours.
  • A response of 401, 403 or 410, or a destination that Sendora refuses to call (for example a private network address or an endpoint that has been deactivated), is treated as permanent. Sendora does not retry these, and the delivery is marked failed straight away.
  • After the last attempt (or a permanent failure) the delivery is marked failed; check the delivery log.
  • After 5 consecutive failed deliveries (a delivery counts as failed once its retries are used up), Sendora disables the endpoint automatically so it stops receiving events. Fix the cause, then re-enable it by updating the endpoint with is_active set to true (PATCH /webhook-endpoints/{endpoint_id}). A successful delivery resets the count.

Reading endpoints and delivery history

One endpoint lists your webhook endpoints and returns a single one. Lists accept page and limit and report X-Total-Count.
deliveries is a list of recent delivery attempts with status codes, durations, and error messages.

Updating, rotating and testing an endpoint

PATCH /api/v1/public/webhook-endpoints/{endpoint_id} changes the endpoint and can rotate its secret and send a test event in the same call:
The steps run in this order: settings, secret rotation, test event.

Best practices

  1. Acknowledge fast, process async, return 200 immediately, then handle the event in a queue/worker
  2. Make handlers idempotent, the same delivery may be attempted more than once; use a stable event-specific identifier when one is present, or deduplicate using your own delivery ledger
  3. Always verify signatures, reject anything with an invalid or missing signature header
  4. Monitor the delivery log, set up alerts if failure rate climbs