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
| Item | Value |
|---|---|
| Method | POST |
| Content-Type | application/json |
| Endpoint | Must be HTTPS |
| Success ack | Any HTTP 2xx (response body is ignored) |
| Retries | Up 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
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | Exotel-Hermix/<version> |
X-Exotel-Event-Sid | Same as event_sid in the body |
X-Exotel-Request-Id | <event_sid>-<attempt_number> (1–3) |
Authorization | Basic … 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"
}
}
| Field | Type | Description |
|---|---|---|
event_sid | string | Unique event ID |
event_type | string | Coarse group: leg_lifecycle_event, leg_action_event, bridge_lifecycle_event, bridge_action_event |
event_name | string | Specific event (e.g. leg_answered, gather_success) |
event_timestamp | string | RFC 3339 UTC with millisecond precision |
action_sid | string | Present when an action triggered this event |
action_custom_parameter | string | Echo of action_custom_param from your action request |
event_data | object | Action or error details |
data | object | Leg/bridge context (sid, state, timestamps, etc.) |
Event names
Leg lifecycle
leg_connecting— Exotel is diallingleg_ringing— Ringing on the recipient's endleg_answered— Call picked upleg_incoming— Inbound call receivedleg_terminated— Call endedleg_failed_to_create— Leg creation failed
Leg action outcomes
play_started,play_completed,play_interrupted,play_failed_to_startgather_initiated,gather_started,gather_success(includesdigits),gather_failed,gather_interrupteddial_initiated,dial_success,dial_completed,dial_failedrecording_started,recording_stopped,recording_availablehold_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