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
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 theevent_type field:
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
call.completed
call.completed
meeting.booked
meeting.booked
booked_via is either "voice_agent" (AI booked during a call) or "operator" (manual booking in Unibox).campaign.finished
campaign.finished
lead.enriched
lead.enriched
Verifying signatures
Sendora signs every delivery with HMAC-SHA256 using the endpoint’ssecret. 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.
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:
Delivery flow
Delivery and retries
- Sendora expects your endpoint to return
2xxwithin 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,403or410, 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 markedfailedstraight 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_activeset totrue(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 acceptpage 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
- Acknowledge fast, process async, return
200immediately, then handle the event in a queue/worker - 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
- Always verify signatures, reject anything with an invalid or missing signature header
- Monitor the delivery log, set up alerts if failure rate climbs