Skip to main content
The CDR webhook sends a call detail record (CDR) to your endpoints after each call ends. You can add up to five destinations, and each enabled destination gets its own delivery of every call, with the direction, outcome, timings, the agent who handled it and a link to the recording if there is one. Use it to keep a CRM, data warehouse or billing system up to date without polling. There’s one event type: call completed. You don’t subscribe to individual events.

Set up a destination

1

Open the webhook settings

Sign in as a company admin and go to Integrations → CDR Webhook. Until you add a destination, the list shows No destinations yet.
2

Add a destination

Click Add destination and give it a Name, for example Data warehouse, so you can tell your destinations apart.
3

Enter your endpoint

In Endpoint URL, enter the full http:// or https:// address of your receiver, up to 1,024 characters. It must be reachable from the public internet. Use HTTPS in production.
4

Choose method, body format and retries

  • Method: POST (default), PUT or GET. GET sends the fields in the query string and ignores the body format.
  • Body format: JSON (default) or Form data (application/x-www-form-urlencoded).
  • Retry attempts: 0 to 5. The default is 3.
5

Choose authentication (optional)

Under Authentication, choose an Authentication type: None, Bearer token, Basic auth or Custom header. Then fill in the fields it shows. See Authenticate deliveries.
6

Save

Click Save destination. The destination is enabled straight away and its status shows Active.
Integrations > CDR Webhook tab with Call records (CDR) destinations, the Add destination button, the No destinations yet empty state and the retry note
Add destination dialog with Name, Endpoint URL, Method POST, Body format JSON, Retry attempts 3 and Authentication type None

Manage destinations

Each row in the list shows the destination’s name, endpoint, method and format, authentication and status.
  • Use the on/off switch to turn one destination off or on. A destination that’s off is skipped; the others keep receiving calls.
  • Edit: change any setting. Leave the secret blank to keep the saved one, as long as you keep the same authentication type.
  • ⋯ → Delete: remove the destination after you confirm. Deleting the last destination removes the webhook, and calls are no longer delivered.
  • Pause all / Resume all: stop or restart delivery to every destination without changing their settings.
You can have up to five destinations. Two destinations can’t use the same endpoint and method.
If you set up the webhook before multiple destinations were available, your existing endpoint appears as the first destination. Nothing needs to change.
Calls between two internal extensions aren’t delivered. The webhook only reports calls with an outside party.

Authenticate deliveries

TalkChief doesn’t sign webhook requests. To check that a request came from TalkChief, set a credential that TalkChief sends with every delivery, and have your endpoint check it.
  • The credential is one your endpoint expects. It’s not a TalkChief API key.
  • Secrets can be up to 2,048 characters and can’t contain line breaks. A basic auth username can’t contain a colon.
  • A custom header name can only contain letters, digits, the backtick and these symbols: ! # $ % & ' * + . ^ _ | ~ -. You can’t use Host, Content-Length, Content-Type, Transfer-Encoding, Connection, User-Agent or Accept, because TalkChief sets these itself.
  • You enter the secret but never see it again. The app only shows that a secret is saved, plus its last four characters for longer secrets. If you leave the field blank when you save, the stored secret is kept, as long as you haven’t changed the authentication type.
  • If you switch the type to None and save, the stored credential is removed.
  • TalkChief never follows redirects, so the credential only ever goes to the exact endpoint you entered.

Payload

Every delivery contains these fields. With JSON, the body is UTF-8, and non-Latin names arrive as readable text, not escape codes. With form data or GET, null values are sent as empty strings and booleans as true/false.

Fields

string
required
A stable, unique ID for the call. Use it to deduplicate. If a call is delivered again, it has the same providerCallId.
string
required
inbound or outbound.
string
required
One of answered, busy, no-answer, cancelled, abandoned, voicemail, congestion or failed. abandoned means an inbound caller hung up before anyone answered. cancelled is the outbound equivalent.
string
required
The calling number, in E.164 format when it’s a real phone number. Internal extensions appear exactly as dialed.
string
required
The called number. Same format as from.
string
required
When the call started, in ISO 8601 with a UTC offset, in your account’s time zone.
string | null
When the call was answered. null if it was never answered.
string | null
When the call ended.
integer
required
Billed talk time, in seconds. It doesn’t include ringing, so it’s not endedAt − startedAt. endedAt − answeredAt always equals durationSeconds.
integer
How long the call rang, as the phone platform reports it. A call has several legs and this figure covers only one of them, so it may not equal answeredAt − startedAt.
integer
The whole call including ringing. Always equals endedAt − startedAt.
string
required
Extension of the member who answered an inbound call or placed an outbound one.
string | null
The member’s name, in UTF-8.
string | null
The member’s email address. Unlike the extension, it’s a stable identifier.
string | null
The team the member belongs to.
string | null
The ID of one underlying call leg. For troubleshooting only. Don’t deduplicate on it, because one call has several legs.
string | null
The caller ID name as it was shown, in UTF-8.
string | null
The URL of the call recording, if there is one. Calls with no talk time never include a recording.
boolean
required
true exactly when recording contains a URL.
string | null
The queue the call came through, if any.
string | null
The raw hang-up cause from the phone platform, for example NORMAL_CLEARING.
string | null
The SIP response code, for example 200 or 486.
string | null
Your account ID on the TalkChief phone platform.
To transcribe a delivered call, send its recording URL to the AI Transcription API.

Respond and handle retries

  • Each destination is delivered and retried on its own. If one endpoint is down, the others still receive the call on time, and a destination that already acknowledged a call isn’t sent it again.
  • Reply with any 2xx status to acknowledge a delivery. Each attempt waits up to 15 seconds for your reply.
  • TalkChief retries when it can’t connect, when the request times out, or when you reply with 408, 425, 429 or any 5xx. Retries are spaced further apart each time: after 30 seconds, 2 minutes, 10 minutes, 30 minutes and 1 hour. Each destination’s Retry attempts sets how many of these steps are used for that destination. A value of 0 is treated as the default of 3.
  • Any other 4xx reply, such as 400, 401, 404 or 422, counts as a permanent failure for that destination, and that call isn’t retried to it.
  • If your endpoint keeps failing, the webhook can be switched off automatically. The CDR Webhook page then shows Disabled and the reason. Fix the endpoint and save the destination to switch it back on.
Each call arrives once in normal operation. A delivery that TalkChief couldn’t confirm may be sent again, though, so always deduplicate on providerCallId.

Timing

TalkChief waits about 90 seconds after a call ends before delivering it. This lets every part of the call, including the recording, be combined into one record. Expect each record to arrive roughly a minute and a half to two minutes after the call ends.

Troubleshooting

Member information isn’t being attached to deliveries. Edit any destination on the CDR Webhook page and click Save destination to restore it.
Another webhook on your account also reports completed calls, so the same call can reach you twice. The page lists the other webhooks by name and address. If you don’t recognize one, contact TalkChief support.
Check that the authentication type isn’t None and that a secret is saved. If a stored value is malformed, TalkChief sends no authentication header at all rather than a broken one, so your endpoint should reply 401.
The recording wasn’t ready in time to include it. The record isn’t updated later. Recordings are only sent for calls that were recorded and had talk time.