Webhook documentation
Voice Calling Webhooks & Call Status Notifications
A voice call webhook is an HTTPS callback that a voice platform uses to tell your system what happened to an automated call: whether it rang and was answered, how long it lasted, which IVR keys were pressed, or why it did not connect.
Updated
How automated voice call callbacks work
Outbound voice broadcasts (OBD), IVR campaigns and voice OTP calls are placed by a voice platform on your behalf. A callback reports the result back to you. Platforms differ in how much detail they send: some post every progress step of every call, others send one final call record per call or a summary per campaign.
Call initiated and ringing
Initiated means the platform accepted the call request and started dialling. Ringing means the destination network reported that the phone is ringing. These progress events are useful for live dashboards but are not outcomes; a call that rang can still end unanswered.
Answered and completed status
Answered is reported when the call connects. Completed marks the end of an answered call and usually carries the duration. Answer detection is not perfect: voicemail or network announcements can register as answered on some routes, so short durations are worth reviewing.
Failed, busy and no-answer outcomes
| Outcome | Typical meaning | Reasonable next step |
|---|---|---|
| Busy | The line was engaged. | Retry later, within your attempt limit |
| No answer | The phone rang but nobody picked up. | Retry at a different time of day, or use another channel |
| Failed | The call could not be placed, for example an invalid or unreachable number. | Check the number; do not retry repeatedly |
Set a maximum number of attempts per number and respect calling-hour and consent rules for your category of call; see Voice Calling for compliance basics.
Call duration
Completed calls usually report how long the call was connected. Some platforms also report ring time, or a billed duration rounded to a billing unit. Store the raw values with their units and name them clearly (for example duration_seconds) so connected time and billed time are never confused in reports.
IVR keypress events where supported
IVR calls ask the listener to press a key, such as “press 1 to confirm, 2 to reschedule”. Where the platform supports it, the keys pressed (DTMF digits) are reported either as separate events or as a field on the final call record, sometimes with the menu they belong to.
- Map each key to an action on your side and ignore keys that are not part of the menu.
- If a call can have several menus, record which menu each keypress answered.
- Treat keypress data as potentially sensitive, since some flows collect codes or account digits. Do not log it.
Illustrative voice call event
{
"event_id": "evt_example_004",
"event_type": "call.completed",
"call_id": "call_example_321",
"channel": "voice",
"status": "COMPLETED",
"duration_seconds": 38,
"dtmf": "1",
"timestamp": "2026-11-08T10:41:05Z"
}Voice events identify the call rather than a message, so this illustration uses call_id in place of a message ID and adds duration_seconds and dtmf. status is the call outcome, channel is voice, and timestamp marks when the call ended.
Voice campaign reporting
| Measure | Calculation |
|---|---|
| Answer rate | Answered calls ÷ calls attempted |
| Average connected duration | Total connected seconds ÷ answered calls |
| Keypress response rate | Answered calls with a valid keypress ÷ answered calls |
| Retry yield | Numbers answered on a retry ÷ numbers retried |
Callback URL handling
- Use a dedicated HTTPS path for voice events, separate from SMS or WhatsApp, to simplify monitoring.
- Acknowledge each event quickly; large campaigns can produce bursts of thousands of call records within minutes.
- Queue events and update your records asynchronously so a slow database does not cause retries.
Event processing and security
Verify each callback with the authentication method confirmed for your account, deduplicate on the event ID, and keep only the latest outcome per call while retaining raw events for audit. The webhook security guide explains signatures, replay protection and safe logging, and the Node.js and Python guides show complete receivers you can adapt.
Troubleshooting voice callbacks
| Symptom | Likely cause | What to check |
|---|---|---|
| Calls show as completed but no duration is stored | Duration arrives on a later event, or under a different field name | Whether your platform sends duration on the final event or a separate call record |
| Answered calls recorded as no answer | An interim event processed after the final one overwrote it | Ordering guard: never replace a final outcome with an interim status |
| Keypresses missing for some calls | The caller pressed a key before the prompt finished, or the platform reports digits only on the final record | Barge-in settings for the IVR flow and the event that carries DTMF data |
| Duplicate outcomes for one call | The platform retried after a slow or failed response from your endpoint | Response times, and deduplication on the event ID |
| Very high failure counts at campaign start | Malformed numbers in the upload, or calls attempted outside permitted hours | Number formatting (country code, 10 digits) and campaign scheduling |
When you raise an issue with support, share the call ID, the campaign or flow name and the approximate time of the call rather than the full phone number or recording.
Frequently asked questions
What events does a voice call webhook send?
Typically call progress (initiated, ringing, answered) and a final outcome (completed, busy, no answer or failed), often with duration and IVR keypresses. The exact events depend on the voice platform and must be verified for your account.
How do I receive IVR keypresses?
Where supported, keypresses are reported as separate events or as a field on the final call record. Map each digit to an action and ignore digits outside the menu.
Should I retry busy and no-answer calls automatically?
You can, within a fixed attempt limit and permitted calling hours. Do not keep retrying numbers that fail because they are invalid.
