Payload Spec

Delivery format

JSON over HTTPS POST. Content-Type: application/json.

note

Only Custom endpoints receive the structure on this page verbatim. Slack / Teams / Email deliveries are transformed internally into the appropriate format (formatted text posts / email).

Sample payload (Custom endpoint)

{
  "message": "[Recho] Outbound call error\n━━━━━━━━━━━━━━\ncallId: abc-123\ncallStatus: CALLING\ncallSid: CA94b51...\nclientId: client-1\n━━━━━━━━━━━━━━\nErrors:\n  - [CALL_CONNECTION_FAILED] Failed to initiate or connect the call.\n━━━━━━━━━━━━━━\nTime: 2026-05-12 10:24:00",
  "data": {
    "callId": "abc-123",
    "callStatus": "CALLING",
    "callSid": "CA94b51...",
    "clientId": "client-1"
  },
  "errors": [
    {
      "code": "CALL_CONNECTION_FAILED",
      "message": "Failed to initiate or connect the call.",
      "timestamp": "2026-05-12T10:23:45.000Z"
    }
  ]
}

TypeScript types

Type definitions matching the sample above:

type WebhookPayload = {
  message: string; // key name is configurable via contentKey (default: message)
  data: WebhookData;
  errors?: CallError[]; // only on error
};

type WebhookData = {
  callId: string;
  callStatus: string;
  callSid: string; // empty string when absent
  clientId: string; // empty string when absent
};

type CallError = {
  code: WebhookErrorCode; // error category (see /webhooks/error-codes)
  message: string; // fixed English message per category
  timestamp: string; // ISO 8601 (UTC)
};

type WebhookErrorCode =
  | 'CALL_NOT_PERMITTED'
  | 'CALL_CONNECTION_FAILED'
  | 'CALL_INTERRUPTED'
  | 'CALL_RESULT_PROCESSING_FAILED'
  | 'ANALYZER_FAILED'
  | 'INTERNAL_ERROR'
  | 'UNKNOWN_ERROR';

Top-level fields

Field	Type	How to use it
message	string	Display-oriented formatted text (human-readable). Includes newlines (\n) and separator lines. Stream it to logs or notification forwarding. Do not parse it programmatically. The key name is configurable via the webhook contentKey setting (default: message).
data	WebhookData	Machine-readable identification info. Programs should reference this.
errors	Array<CallError> | undefined	Present only on error. Detect errors via errors?.length and use the array for detail logs and notifications.

data fields (call identification)

Field	Type	How to use it
callId	string	Unique call ID. The primary key for identifying the call in external systems. Deliveries for the same callId are FIFO-ordered (see Setup Guide).
callStatus	string	Call status at notification time. See Call Status Reference for values. Not usable for error detection (use the errors array).
callSid	string	Telephony-provider-side call ID (empty string when absent). For correlating with provider logs.
clientId	string	Client identifier (optional; empty string when absent). Passes through the application-side ID specified when placing the call.

Inbound per-status triggers omit callSid / clientId

INBOUND_CALL_* carry only callId / callStatus in data (INBOUND_CALL_ERROR adds callSid, for three keys). All four keys above are present for outbound triggers and for CALL_LOG_CREATED.

CALL_LOG_CREATED adds a direction key to data

The call-log trigger (see Setup Guide) carries no direction in its trigger name, so it adds direction (OUTBOUND / INBOUND) to the four keys above. It is the only trigger with this field.

ACW completion notifications use a different data

For ACW (After Call Work) agent completion notifications, data contains only the four keys below. callStatus / callSid / clientId from the table above are not included.

Field	Type	How to use it
callId	string	ID of the call the post-processing ran against.
acwAgentId	string	ID of the ACW agent that ran.
acwResultId	string	ID of the recorded result. Fetch the result itself via GET /v1/acw-results.
isError	string	Whether the agent run failed, as the string 'true' or 'false'.

Requests to ACW agents (what a Self Provided Agent receives as the launch request) also use the same standard payload described on this page. Their data carries the keys from the "data fields" table above plus projectId (the ID of the project the call belongs to). Authentication and retry behavior are the same as for regular webhooks; respond with 2xx (3xx is treated as an error).

errors[] (error details)

Included only when errors occurred: an array of one or more error objects (code / message / timestamp). See Error Codes for the meaning of each field and the possible code values.

Authentication

Credentials (Bearer token / RSA-SHA256 signature) are attached to the request headers, not the payload. See Authentication for verification.