call.* events to your server the moment they happen -
call started, ended, analysis done, processing complete (recording), transfers - so you don’t have to
poll. Every delivery is HMAC-signed so you can verify it came from Vocily.
Set up an endpoint
Webhooks are configured per agent, in the dashboard:1
Open the agent
Go to Agents → your agent → Settings → Webhooks.
2
Add an HTTPS endpoint
Enter your receiver URL, choose which events to subscribe to, and set (or generate) a signing
secret. Save it - you’ll need it to verify signatures.
3
Return 2xx fast
Your endpoint should acknowledge with a
2xx within 10 seconds, then process asynchronously.An endpoint is always active - to stop delivery, delete it. There’s no enable/disable toggle.
The envelope
Every event is a POST with this JSON body:Delivery headers
Vocily-Signature on every request - see Verifying signatures.
The Vocily-Event-Id header is a convenience mirror; dedupe on the body’s event_id, not the header.
Delivery guarantees
At-least-once
An event may arrive more than once. Make your handler idempotent - dedupe on
event_id.No guaranteed order
Order by
sequence (or occurred_at), not arrival order.Retries with backoff
Up to 3 attempts spaced
0s → 2m → 15m. A 429/503 with Retry-After is honored.Always active
A dead endpoint keeps being retried until attempts are exhausted; it’s never auto-disabled. Delete
it to stop.
See all events →
The 5
call.* events with complete payload examples.