This is the current API V1 documentation. Explore our API V2 if you’d like to test new features.

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.

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 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. 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
direction Whether the call is 'incoming' or 'outgoing'
state Whether the call is in 'bridging' or 'parked' state