What Are Webhooks?
Webhooks are HTTP callbacks that TopCalls sends to your server when events occur. They’re the best way to integrate TopCalls with your existing systems.Real-Time Updates
Get notified when calls complete or fail. No polling required.
Complete Data
Receive full call details, transcripts, recordings, and analysis in a single webhook payload.
Reliable Delivery
Built-in retry logic ensures webhooks are delivered even if your server is temporarily unavailable.
Filterable
Subscribe to specific dispositions or conversions instead of receiving every event.
How Events Are Delivered
There are two delivery channels:| Channel | How to set up | What it receives |
|---|---|---|
Per-call webhook_url | Set on POST /v1/calls (or in the campaign editor) | One payload when that call completes, fails, or is cancelled |
| Account-level subscription | POST /v1/webhooks | Every matching event on the account, regardless of how the call was created |
Available Events
Subscriptions use these event names:| Event | When It Fires |
|---|---|
call.completed | Any call finishes and post-call processing is done |
call.completed.<disposition> | A call finishes with a specific disposition, e.g. call.completed.booked_callback |
Booked Callback becomes booked_callback). Combine events with filters on the subscription, including the is_conversion flag, to narrow delivery further.
The event names
lead.status_changed, campaign.activated, and campaign.paused are reserved for future use. The API accepts subscriptions for them, but they do not fire yet.status field (completed, failed, or cancelled), so a single endpoint can handle successful and failed calls.
Webhook Timing
Successful Calls
Webhooks are sent ~15 seconds after call ends to ensure:- Recording URL is available
- Transcript is complete
- Call summary is generated (if configured)
Failed Calls
Webhooks are sent immediately when the call fails (no recording to wait for).Webhook Retries
TopCalls automatically retries failed webhook deliveries:- Initial attempt: Immediate
- Retry 1: After 1 minute
- Retry 2: After 5 minutes
- Retry 3: After 15 minutes
- Retry 4: After 30 minutes
- Retry 5: After 1 hour
Next Steps
Webhooks Guide
Learn how to set up and handle webhooks in your application.
API Reference
See the complete API documentation.