Receiving Webhooks' fill-rule='evenodd'%3E %3Cpath d='M7.778 7.975a2.5 2.5 0 0 0 .347-3.837L6.017 2.03a2.498 2.498 0 0 0-3.542-.007 2.5 2.5 0 0 0 .006 3.543l1.153 1.15c.07-.29.154-.563.25-.773.036-.077.084-.16.14-.25L3.18 4.85a1.496 1.496 0 0 1 .002-2.12 1.496 1.496 0 0 1 2.12 0l2.124 2.123a1.496 1.496 0 0 1-.333 2.37c.16.246.42.504.685.752z'/%3E %3Cpath d='M5.657 4.557a2.5 2.5 0 0 0-.347 3.837l2.108 2.108a2.498 2.498 0 0 0 3.542.007 2.5 2.5 0 0 0-.006-3.543L9.802 5.815c-.07.29-.154.565-.25.774-.036.076-.084.16-.14.25l.842.84c.585.587.59 1.532 0 2.122-.587.585-1.532.59-2.12 0L6.008 7.68a1.496 1.496 0 0 1 .332-2.372c-.16-.245-.42-.503-.685-.75z'/%3E %3C/g%3E %3C/svg%3E)
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_id
s within 60 seconds will be ignored.
Example: 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:
{
"record_type": "event",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"event_type": "call_initiated",
"created_at": "2018-02-02T22:25:27.521992Z",
"payload": {
"to": "+12025550131",
"start_time": "2018-02-02T22:25:27.521992Z",
"from": "+1-202-555-0133",
"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",
"direction": "incoming",
"state": "parked"
}
Field | Value |
---|---|
record_type | Description of the record. |
id | unique id for the webhook |
event_type | The type of event detected by the Telnyx system |
created_at | ISO-8601 datetime of when event was created |
to | Destination number or SIP URI of the call |
start_time | ISO-8601 datetime of when call was received | from | Number or SIP URI placing the call |
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 |
direction | Whether the call is 'incoming' or 'outgoing' |
state | Whether the call is in 'bridging' or 'parked' state |