Call Detail Record (CDR) Webhooks
Overview
SimpleVoIP provides call reports through the customer admin portal. For ongoing integrations with reporting, analytics, or other business systems, CDR webhooks send call information automatically.
SimpleVoIP can configure webhook notifications to one or more URLs for completed inbound and outbound calls. Each notification contains a JSON object describing the call.
Contact your account manager to configure a destination URL, authentication, or a custom payload.
Webhook Request Format
Notifications use HTTP POST with the following content type:
Content-Type: application/jsonThe tables below describe the default payload. Custom integrations may use a different payload or include additional fields.
Call and Site Information
| Property | JSON type | Description |
|---|---|---|
call_id |
string | Call ID of the call’s root leg. |
account_id |
string | Kazoo account ID associated with the call. |
timestamp |
integer | Call start time as a UNIX timestamp, in seconds. |
datetime_local |
string | Call start time in ISO 8601 format, using the site’s configured time zone and UTC offset. |
site_name |
string | Site name. |
site_number |
string | Site number or identifier. |
direction |
string |
inbound or outbound, based on the party that initiated the call. |
caller_id_number |
string | Caller’s number, normalized to E.164 format when possible; otherwise, the available caller ID value. |
caller_id_name |
string | Caller’s name, when available. |
callee_id_number |
string | Called party’s number, normalized to E.164 format when possible; otherwise, the available callee ID value. |
callee_id_name |
string | Called party’s name, when available. |
Duration and Call Outcome
| Property | JSON type | Description |
|---|---|---|
total_duration_secs |
integer | Duration of the call’s root leg, in seconds, including ringing. |
total_billing_secs |
integer | Seconds of active media on the call’s root leg. This can include time spent in an automated menu. |
total_user_talk_time |
integer | Sum of active-media seconds across SimpleVoIP user/device legs. |
max_user_ring_time |
integer or null | Longest ring time among SimpleVoIP user/device legs for an inbound call. Returns 0 if there are no user/device legs and null for outbound calls. |
hangup_cause |
string | Hangup cause reported for the call’s root leg. |
was_missed |
boolean |
true when an inbound call rang a SimpleVoIP user/device for more than zero seconds and no user/device leg was answered. |
was_park_abandoned |
boolean |
true if any leg of the call ended while parked. |
Answering, Routing, and Additional Data
| Property | JSON type | Description |
|---|---|---|
first_answered_user |
string or null | ID of the first answering SimpleVoIP user, when available. Returns null for outbound calls. |
first_answered_device |
string or null | ID of the first answering SimpleVoIP device, when available. Returns null for outbound calls. |
attempted_users |
array of strings | Unique user IDs associated with attempted SimpleVoIP user/device legs. Returns an empty array for outbound calls. |
attempted_devices |
array of strings | Unique device IDs associated with attempted SimpleVoIP user/device legs. Returns an empty array for outbound calls. |
menu_selections |
array of strings | Menu or routing labels inferred from caller ID information on user/device legs. Availability depends on callflow configuration. Returns an empty array for outbound calls. |
recording_ids |
array of strings | Recording identifiers associated with the call’s legs. |
custom_application_vars |
object | Custom application variables from the call’s root leg. Returns an empty object when none are present. |
Example Payload
The following illustrative example shows an inbound call that passed through a menu and was answered by a user:
{
"call_id": "example-call-123@example.invalid",
"account_id": "df52f40b0e10163a25d44f7fdf2aa8a1",
"timestamp": 1700000000,
"datetime_local": "2023-11-14T17:13:20-05:00",
"site_name": "Example Store",
"site_number": "125",
"total_duration_secs": 177,
"total_billing_secs": 176,
"hangup_cause": "NORMAL_CLEARING",
"direction": "inbound",
"caller_id_number": "+12025550123",
"caller_id_name": "EXAMPLE CALLER",
"callee_id_number": "+12025550124",
"callee_id_name": "",
"total_user_talk_time": 150,
"max_user_ring_time": 12,
"first_answered_user": "aabbccddeeff00112233445566778899",
"first_answered_device": "11223344556677889900aabbccddeeff",
"attempted_users": [
"aabbccddeeff00112233445566778899"
],
"attempted_devices": [
"11223344556677889900aabbccddeeff"
],
"menu_selections": [
"Opt 2"
],
"recording_ids": [
"202311-82ed6ac2634a76cc4b01785121b84837"
],
"was_park_abandoned": false,
"was_missed": false,
"custom_application_vars": {}
}Understanding Call Metrics
Duration, Billing Seconds, and User Talk Time
These fields measure different parts of a call:
-
total_duration_secsincludes ringing and active media on the root leg. -
total_billing_secsmeasures active media on the root leg. An automated menu can start media before a person answers. -
total_user_talk_timeadds together active-media time across SimpleVoIP user/device legs. Because it is a sum across legs, it is not necessarily the elapsed duration of the call.
For a call that rings directly to a recipient, billing seconds are generally the total duration minus ringing time. For a call answered immediately by an automated menu, billing seconds may be close to the total duration.
A positive total_billing_secs value does not establish that a person answered.
Maximum User Ring Time
For inbound calls, max_user_ring_time is the longest time any SimpleVoIP user/device leg rang before it was answered or ended.
- A value greater than
0indicates recorded user/device ringing time. - A value of
0can occur when the call has no user/device legs or no recorded ringing time. - Outbound calls return
null.
Do not use max_user_ring_time == null to identify inbound calls that remained in an automated menu.
Missed Calls
Use was_missed to identify inbound calls that rang a SimpleVoIP user/device but were not answered by one.
This field is not a general indicator of every unsuccessful call. For example, a caller who hangs up in an automated menu before any user/device rings does not meet this definition of a missed call.
Outbound calls return false.
Calls That End While Parked
was_park_abandoned is true when any call leg ends while parked. This can occur after a user has already answered the call, so it is separate from was_missed.
Menu Activity
menu_selections contains labels inferred from call routing information. It is not a complete record of every key pressed or every menu visited.
An empty array does not prove that the caller never entered a menu. Similarly, positive billing seconds combined with zero user ringing may indicate automated handling, but cannot establish whether the caller completed their intended task.
Use these fields with knowledge of your callflow when building menu-handling reports.
Hangup Cause
hangup_cause contains the underlying platform’s reason for ending the root call leg. Interpret it alongside the answering, ringing, and missed-call fields.
For example, NORMAL_UNSPECIFIED is a fallback cause and should not be interpreted as proof that nobody answered or that no overflow destination was configured. See the FreeSWITCH call-setup documentation for details about cause-code mappings.
Authentication
CDR webhooks support the following authentication options:
| Option | How it works |
|---|---|
| No authentication | No authentication credential is added to the request. |
| Bearer token | A configured token is supplied in the Authorization header. |
| Query parameter | A configured credential is supplied in a named URL query parameter. |
Contact your account manager to select an authentication method and configure the required credential. For query-parameter authentication, specify the parameter name expected by your receiving system.
Frequently Asked Questions
Can the webhook body be customized?
Yes. SimpleVoIP can configure a custom payload for your integration. Custom development may require engineering time and incur additional costs. Contact your account manager to discuss your requirements.
Can the payload include individual call legs?
Yes. An optional payload format includes the default fields plus a legs array containing individual call-leg details. The default payload does not include this array.
Are recording files included?
No. recording_ids contains recording identifiers, not audio files or download URLs.
Why are some fields empty or null?
Some information may be unavailable or may not apply to a call. For example:
- Caller or callee names may be empty strings.
- Outbound calls have
nullfirst-answer fields and empty attempted-user/device arrays. - Calls without recording identifiers have an empty
recording_idsarray. - Calls without custom application variables have an empty
custom_application_varsobject.
Your integration should preserve the distinction between null, 0, empty strings, empty arrays, and empty objects.