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'
  | '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.

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.