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

Open SidemenuDocs
Docs
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 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.

Example: Receiving a Webhookexample--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": "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": "http://example.com/webhooks"
  }
}
FieldValue
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 call control API
connection_idTelnyx 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
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

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