Skip to main content

HTTPS Event Endpoint

Exotel delivers live call events to a public HTTPS endpoint you host. Your server acknowledges each event with an HTTP 2xx response, then issues the next action via the ExoML actions API.

Request contract​

ItemValue
MethodPOST
Content-Typeapplication/json
EndpointMust be HTTPS
Success ackAny HTTP 2xx (response body is ignored)
RetriesUp to 3 attempts for 408, 429, 5xx, timeouts, and connection errors. Other 4xx responses are not retried; event is dropped after the final attempt.
Per-attempt timeout~1 second

Request headers​

HeaderValue
Content-Typeapplication/json
User-AgentExotel-Hermix/<version>
X-Exotel-Event-SidSame as event_sid in the body
X-Exotel-Request-Id<event_sid>-<attempt_number> (1–3)
AuthorizationBasic … when Basic Auth is configured

Payload fields​

{
"event_sid": "<event_sid>",
"event_type": "leg_action_event",
"event_name": "leg_answered",
"event_timestamp": "2026-01-15T10:30:00.529Z",
"action_sid": "<action_sid>",
"action_custom_parameter": "your-tracking-value",
"event_data": {
"data": {}
},
"data": {
"leg_sid": "<leg_sid>",
"account_sid": "<account_sid>",
"contact_uri": "+91XXXXXXXXXX",
"exophone": "+91YYYYYYYYYY",
"state": "in-progress",
"start_time": "2026-01-15T10:29:59.312Z",
"end_time": null,
"date_created": "2026-01-15T10:29:59.339Z",
"date_updated": "2026-01-15T10:30:00.112Z"
}
}
FieldTypeDescription
event_sidstringUnique event ID
event_typestringCoarse group: leg_lifecycle_event, leg_action_event, bridge_lifecycle_event, bridge_action_event
event_namestringSpecific event (e.g. leg_answered, gather_success)
event_timestampstringRFC 3339 UTC with millisecond precision
action_sidstringPresent when an action triggered this event
action_custom_parameterstringEcho of action_custom_param from your action request
event_dataobjectAction or error details
dataobjectLeg/bridge context (sid, state, timestamps, etc.)

Event names​

Leg lifecycle

  • leg_connecting — Exotel is dialling
  • leg_ringing — Ringing on the recipient's end
  • leg_answered — Call picked up
  • leg_incoming — Inbound call received
  • leg_terminated — Call ended
  • leg_failed_to_create — Leg creation failed

Leg action outcomes

  • play_started, play_completed, play_interrupted, play_failed_to_start
  • gather_initiated, gather_started, gather_success (includes digits), gather_failed, gather_interrupted
  • dial_initiated, dial_success, dial_completed, dial_failed
  • recording_started, recording_stopped, recording_available
  • hold_success, hold_failed

Example handler (Node.js / Express)​

const express = require('express');
const app = express();
app.use(express.json());

app.post('/exotel/events', async (req, res) => {
// Acknowledge immediately
res.sendStatus(200);

const { event_name, data } = req.body;

if (event_name === 'leg_answered') {
// Issue the first action after ack
await sendExomlAction(data.leg_sid, `
<?xml version="1.0" encoding="UTF-8"?>
<Flow>
<StartSay language="en" preferredTTSEngine="polly">
Welcome. Press 1 for sales, 2 for support.
</StartSay>
</Flow>
`);
}

if (event_name === 'gather_success') {
const digit = req.body.event_data?.data?.digits;
if (digit === '1') {
await sendExomlAction(data.leg_sid, buildDialAction('+918030752400'));
}
}
});

Registering the endpoint​

Outbound / API-driven calls — Pass the URL when creating the leg:

POST /v2/accounts/{account_sid}/legs

{
"contact_uri": "+91XXXXXXXXXX",
"exophone": "+91YYYYYYYYYY",
"leg_event_endpoint": "https://voice.example.com/exotel/events"
}

Inbound calls (ExoPhone) — Contact Exotel support to attach the URL to your ExoPhone.

Authentication (optional)​

If you want Exotel to authenticate when calling your endpoint, share Basic Auth credentials with Exotel support. Exotel then includes:

Authorization: Basic <base64(username:password)>

on every POST. Validate this header on your server and reject requests without valid credentials.

IP allowlist​

If you restrict inbound traffic by IP, allow these Exotel callback source addresses:

35.154.174.161
13.233.217.51
98.130.5.99