This is the API V2 documentation. To switch out of beta revert back to our API V1.

Open SidemenuDocs
Close Sidemenu

Receiving Webhooksreceiving-webhooks

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 Connection 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.

Example: Receiving a webhookexample--receiving-a-webhook

When you place an incoming call to a number associated with your Call Control Connection, 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": "AgDIxmoRX6QMuaIj_uXRXnPAXP0QlNfXczRrZvZakpWxBlpw48KyZQ==",
      "connection_id": "7267xxxxxxxxxxxxxx",
      "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1",
      "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": ""
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 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
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

Was this page helpful?was-this-page-helpful