Call Lifecycle Webhooks
Receive organization-wide call start, end, and summary notifications for every agent type.
Use organization call lifecycle webhooks to update your CRM or run post-call automation. They are asynchronous notifications, separate from agent webhooks, which supply prompts and tool results during conversations.
Configure notifications
Configure Settings > Webhooks as an owner or administrator. Set a public HTTPS URL and a random signing secret (32–256 letters, digits, underscores or hyphens), then enable notifications. The same endpoint receives call notifications from static, HTTP, and webhook agents and every phone provider, including SIP. This setting does not change agent type, configure custom tools, or provide dynamic prompts. The secret is encrypted and never returned by the settings API. Members have read-only access.
The organization endpoint receives three events:
| Event | When emitted | Call fields |
|---|---|---|
call.started | The call is registered as active | id, agentId, status: "active", provider, direction, fromNumber, toNumber, startedAt |
call.ended | The call completes or fails with an end time | Start metadata, terminal status, endedAt, durationSeconds, transcript |
call.summary | The first generated summary is saved | Terminal metadata, summary, summaryGeneratedAt; no transcript |
All three use the same envelope (id, type, createdAt, organizationId, call), destination and signing secret. Each call/event-type pair has its own stable ID. Start and summary events become eligible for delivery immediately. A delayed start retry still describes the start (status: "active"), even if the call has since ended. Receiving call.started means an active call record exists; it is not a carrier-level answer confirmation.
Summary generation is asynchronous. Short calls or calls without enough retained transcript content may never produce a summary. Summary processing claims do not emit events; the text must actually be persisted. Pending summary delivery is cancelled if the summary is deleted or current transcript privacy/retention settings prohibit sending it. Existing summaries are not replayed on activation; a first summary generated after activation may belong to an older call.
Do not assume delivery order: workers and retries can reorder events. Correlate by call.id and deduplicate by the envelope id, not the call ID.
call.ended is queued atomically when a call reaches completed or failed with an end time. Existing completed calls are not replayed. Delivery starts after a five-second grace period to allow final transcript writes. The payload contains only currently retained transcript messages; disabled storage, strict privacy defaults or retention expiry can leave an empty array. Duration covers the Orbitali session, not any later human conversation after a transfer.
{
"id": "bfc85d17-40c4-4238-b949-753ff0e4025c",
"type": "call.ended",
"createdAt": "2026-10-16T10:00:30.000Z",
"organizationId": "organization-id",
"call": {
"id": "call-id", "agentId": "agent-id", "status": "completed",
"provider": "sip", "direction": "inbound",
"fromNumber": "+34910000001", "toNumber": "+34910000002",
"startedAt": "2026-10-16T10:00:00.000Z",
"endedAt": "2026-10-16T10:00:30.000Z", "durationSeconds": 30,
"transcript": [{"role": "user", "content": "Hola", "occurredAt": "2026-10-16T10:00:01.000Z"}]
}
}
Headers:
X-Orbitali-Event-Id: stable event ID, also in the signed body. Deduplicate this ID.X-Orbitali-Timestamp: Unix seconds for this delivery attempt.X-Orbitali-Signature:v1=plus hex HMAC-SHA256 oftimestamp + "." + rawBody, keyed by the organization signing secret. Compare in constant time and reject timestamps more than five minutes from your clock.
Return any 2xx within 10 seconds. Non-2xx responses (including redirects), timeouts and network failures are retried, up to 8 attempts, with delays of 30, 60, 120, 240, 480, 960 and 1920 seconds. Pending events older than 24 hours expire. Delivery is at least once within this retry policy: a crash after receiver acceptance can cause a duplicate. Persist your deduplication marker together with the business operation. Payloads are rebuilt from retained data for each attempt and can change following privacy updates.
Saving settings cancels pending deliveries, including when disabling or rotating the secret. An in-flight request may finish. Call deletion removes delivery records; caller anonymization cancels pending events. Organization exports include configuration and delivery metadata, without the signing secret. Receiver-side retention and deletion remain your responsibility. No transcript or summary copy is kept in the delivery queue.
Settings API (dashboard session)
These routes use the authenticated dashboard session, not an organization API key. Configure the webhook through Settings → Webhooks when integrating an external receiver.
| Method | Path | Access | Response |
|---|---|---|---|
| GET | /v1/call-webhook | Organization member | 200 with enabled, url, hasSigningSecret, updatedAt |
| PUT | /v1/call-webhook | Owner or admin | 200 with the updated settings, never the secret |
PUT requires enabled (boolean) and url (string, at most 2,048 characters). Use a public HTTPS URL without credentials or a fragment. An empty URL is accepted only while disabled. signingSecret is optional if one is already saved; omit it to preserve the stored secret. When supplied it must contain 32–256 letters, digits, underscores, or hyphens. Enabling requires a saved or newly supplied secret. There is one destination for all three events, not an event-subscription list.
| Status | Meaning |
|---|---|
400, INVALID_WEBHOOK_SETTINGS | Invalid fields, unsupported/private URL, or no signing secret when enabling |
401 | Missing dashboard authentication |
403 | A member attempted an update; owner/admin access is required |
Saving any settings cancels pending deliveries, even if the endpoint is unchanged. Configure your receiver before enabling and make a new test call afterward.
A runnable TypeScript receiver and signed local test accepts all three events, despite its call-ended-webhook directory name. Follow its README to run mock tests and expose your receiver over HTTPS. Its in-memory deduplication is for demonstration; production deduplication must survive restarts.
Verify and process a delivery
- Read the raw request body and the timestamp and signature headers before parsing JSON.
- Reject an invalid timestamp or one more than five minutes from your clock. Calculate HMAC-SHA256 over the exact
timestamp + "." + rawBodybytes using the organization signing secret, and compare thev1=signature in constant time. - Parse the verified body and use its signed
idas the deduplication key. Check thatX-Orbitali-Event-Idmatches that ID. Dispatch on the top-leveltype, notmessage.type. - Durably record acceptance and enqueue processing atomically, then return a 2xx response within 10 seconds. Return a failure if you cannot accept the event so it can be retried.
- Correlate updates by
call.id. Expect different event IDs for start, end, and summary, duplicates of each event, and delivery out of order.
Do not use the agent webhook sha256= verifier for lifecycle notifications. The organization signature is v1= and includes a timestamp; its secret is configured separately from an agent's Server Secret.
Troubleshooting
- No event after enabling: make a new call. Prior events are not replayed. Check the saved URL and enabled state in Settings.
- Signature rejected: use the organization signing secret, the exact raw body, and the delivery timestamp header. Check clock skew and whether the secret was rotated.
- Empty transcript: inspect transcript storage and retention settings. An empty array is valid; it does not necessarily mean the caller was silent.
- No summary event: summaries are asynchronous and are not guaranteed. Do not wait for one before processing the end event.
- Repeated or reordered events: deduplicate by event ID and correlate by call ID; do not assume start arrives first.
- Delivery stops after settings changes: pending events are cancelled. Test with a new call after saving.
Use Calls & Logs to inspect the source call. Keep receiver logs limited to event IDs, types, status, and timing; transcripts and phone numbers require your own retention and deletion controls.