Documentation

Call status webhooks

Ruut Voice notifies your StatusCallback URL whenever a call's state changes, so you can track calls in real time and drive your application's UI or analytics.

Configure

Set StatusCallback (and optional StatusCallbackMethod) when creating a call, or configure the callback on an incoming phone number so all inbound calls report status.

TwiMLxml


const call = await client.calls.create({
  to: "+2348000000001",
  from: "+2348000000002",
  twiml: "Hello",
  statusCallback: "https://app.example.com/calls/status",
  statusCallbackMethod: "POST",
});

Payload

The webhook is a form-encoded POST with the following parameters:

Parameter	Type	Description
`CallSid` optional	`string`	Unique identifier for the call.
`AccountSid` optional	`string`	Your account SID.
`CallStatus` optional	`string`	New status: `queued`, `ringing`, `in-progress`, `completed`, `busy`, `no-answer`, `failed`, `canceled`.
`From` optional	`string`	Caller ID of the initiating party.
`To` optional	`string`	Destination of the call.
`Direction` optional	`string`	`inbound`, `outbound-api`, or `outbound-dial`.
`ApiVersion` optional	`string`	API version (`2010-04-01`).
`CallDuration` optional	`string`	Call duration in seconds (on terminal events).

Example request

POSTbash


POST /calls/status HTTP/1.1
Host: app.example.com
X-Twilio-Signature: BASE64…

CallSid=CA2e9f6b3c&CallStatus=completed&From=%2B2348000000002
&To=%2B2348000000001&Direction=outbound-api&ApiVersion=2010-04-01
&CallDuration=42

Handle it with the SDK

call is done — clean up, notify, or billts


import { parseWebhook, isTerminalWebhook, validateWebhookSignature } from "@ruut/voice-sdk";

const valid = await validateWebhookSignature({
  url: "https://app.example.com/calls/status",
  params: req.body,
  signature: req.headers["x-twilio-signature"],
  authToken: process.env.RUUT_AUTH_TOKEN,
});
if (!valid) return res.status(403).end();

const payload = parseWebhook(req.body);
console.log(`Call ${payload.CallSid} → ${payload.CallStatus}`);

if (isTerminalWebhook(payload)) {
  // call is done — clean up, notify, or bill
}

Status values

See the Calls API status table for a full description of each status.