Skip to main content

Receiving Webhooks for Programmable Voice

When you send a Voice API command and receive a successful response (i.e. 200 OK), you can expect to receive a webhook. The webhook will be delivered to the primary URL specified on the Voice API Application associated with the call. If that URL does not resolve, or your application returns a non 200 OK response, the webhook will be delivered to the failover URL, if one has been specified.

In order to minimize webhook delivery time, Telnyx:

  • does not enforce the order in which webhooks are delivered
  • retries webhook delivery if your application does not respond within a certain time threshold.

As a result, you may encounter:

  • out-of-order webhooks
  • simultaneous (or near simultaneous) webhooks
  • duplicate webhooks

Duplicate webhooks may cause your application to issue duplicate commands. You can instruct Telnyx to ignore duplicate commands by sending a command_id parameter as part of your commands. Commands with duplicate command_ids within 60 seconds will be ignored.

Webhooks contain a variety of ID fields which describe them and correlate them with calls.

Example: Receiving a Webhook

When you place an incoming call to a number associated with your Voice API Application, you will receive a callback for the incoming call. It should look something like the JSON below:

"data": {
"record_type": "event",
"event_type": "call.initiated",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"occurred_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"call_control_id": "d14dbcee-880b-11eb-8204-02420a0f7568",
"connection_id": "7267xxxxxxxxxxxxxx",
"call_leg_id": "d14dbcee-880b-11eb-8204-02420a0f7568",
"call_session_id": "428c31b6-abf3-3bc1-b7f4-5013ef9657c1",
"client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
"from": "+1-202-555-0133",
"to": "+12025550131",
"direction": "incoming",
"state": "parked"
"meta": {
"attempt": 1,
"delivered_to": ""

Note: After pasting the above content, Kindly check and remove any new line added

record_typeDescription of the record.
event_typeThe type of event detected by the Telnyx system
idunique id for the webhook
occurred_atISO-8601 datetime of when event occured
call_control_idcall id used to issue commands via Voice API
connection_idVoice API App ID (formerly Telnyx connection ID) used in the call.
call_leg_idID that is unique to the call and can be used to correlate webhook events
call_session_idID that is unique to the call session and can be used to correlate webhook events. Call session is a group of related call legs that logically belong to the same phone call, e.g. an inbound and outbound leg of a transferred call.
client_stateState received from a command
fromNumber or SIP URI placing the call
toDestination number or SIP URI of the call
directionWhether the call is 'incoming' or 'outgoing'
stateWhether the call is in 'bridging' or 'parked' state

On this page