Receiving Webhooks for Programmable Voice

When you send a Call Control 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 Call Control 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 Call Control 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

Field Value
record_type Description of the record.
event_type The type of event detected by the Telnyx system
id unique id for the webhook
occurred_at ISO-8601 datetime of when event occured
call_control_id call id used to issue commands via call control API
connection_id Call Control App ID (formerly Telnyx connection ID) used in the call.
call_leg_id ID that is unique to the call and can be used to correlate webhook events
call_session_id ID 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_state State received from a command
from Number or SIP URI placing the call
to Destination number or SIP URI of the call
direction Whether the call is 'incoming' or 'outgoing'
state Whether the call is in 'bridging' or 'parked' state