Webhooks
Register endpoints to receive signed call events from the API
Webhooks deliver signed call.started / call.ended / call.failed events for calls placed through the REST API. Endpoints are managed from the dashboard, not the REST API — this keeps endpoint creation bounded (an API-driven script could otherwise create unlimited endpoints, and every call event fans out delivery to each one).
Create a webhook
Open Manage → Webhooks in the dashboard sidebar.
Click Create Webhook.
Enter your HTTPS URL and select the events you want to receive.
Copy the signing secret immediately — it is shown once.
Up to 10 webhooks per organization.
Authorization and headers
Each webhook also supports:
- Authorization — an optional custom credential (bearer token, HMAC, or OAuth 2.0), the same reusable credential system used by an agent's own Server URL. Sent alongside the built-in HMAC signature, not instead of it.
- HTTP Headers — custom headers included with every delivery.
- Timeout — request timeout in seconds (1-60), configurable per webhook.
Manage a webhook
From the same page: Edit the URL, events, headers, or credential; Rotate secret to replace a leaked or aging secret without losing delivery history; Test to send a deterministic webhook.test event; or Delete.
Auto-disable after repeated failures
A webhook that fails delivery 5 times in a row for a single event (retries exhausted) and has accumulated 10 or more consecutive failed deliveries overall is automatically disabled — no further events are sent to it. An in-app notification is sent to your organization the moment this happens, so a broken integration doesn't go unnoticed.
To recover: fix your endpoint, then click Re-enable on the webhook row. This also resets the failure counter, so it isn't one failure away from disabling again.
Agent Server URL webhooks in squads
Besides the organization webhooks above, each agent can have its own Server URL (agent editor, Advanced). It receives that agent's session events: status-update, session-started, conversation-update, tool-calls and end-of-session-report, filtered by the message types you enabled on the agent.
A squad call is one session with several agents, so the question is which agent's Server URL hears it.
| Event | Without squad routing (default) | With squad routing |
|---|---|---|
| Session start, status and end-of-session report | The entry agent | The squad's webhook source, else the entry agent |
| Conversation turns and tool calls | Whichever agent is speaking at that moment | The squad's webhook source, else the entry agent |
Without routing, a handed-off call splits across the Server URLs of its agents and no receiver sees the whole conversation. With routing on, one receiver gets every event of the call, and it uses its own Server URL, headers, credential, static IP and enabled message types as a whole.
Pick the receiver in the squad's Settings, Webhooks. Routed events carry two extra fields on message.call: squadId, and activeAssistantId, the agent that produced the event.
Squad webhook routing is rolled out per workspace and is off by default, so existing squads behave as before until it is enabled. The squad's consistency banner already shows which agents would stop receiving events, so you can review before enabling.
What routing does not change: tool execution requests sent to an agent's own server still go to the agent that owns the tool; organization webhooks are unaffected; process squads are not rerouted. API-only members have no Server URL (see below), and a process member that also has chat or voice keeps sending to the entry agent's Server URL, so nothing splits.
API-only agents
An agent with only the API capability (no chat, no voice) is started by an API call or by a process squad, not by a caller. There is no live conversation to stream, so its Server URL is turned off in the agent editor (Advanced).
Its results arrive through your organization webhooks instead, the same mechanism as other API-driven work. Subscribe to process.started, process.completed and process.failed; each carries the run_id, the squad and agent ids, the input and the output.
Add chat or voice to the agent and the Server URL is available again. A URL saved earlier is kept, not deleted.
Reference
For the event envelope, event types, and signature verification, see Webhooks — API Reference.