Event catalog
Consume Voice API events with confidence.
Use the event catalog to validate payload shape, deduplicate delivery, reconcile call outcomes, and route escalations into business systems.
Event catalog
| Event | When it is emitted | Primary identifiers |
|---|---|---|
voice.call.started | A call is accepted into the runtime and session setup begins. | call_sid, stream_sid, tenant_id |
voice.call.completed | The call ends and final operational state is available. | call_sid, voice_session_id, status |
voice.call.escalated | The agent or supervisor creates a handoff, bridge, or callback path. | call_sid, target, initiated_by |
voice.session.evaluated | A voice session evaluation is recorded for QA or rollout governance. | voice_session_id, score, tags |
voice.webhook.delivery_failed | A configured downstream webhook endpoint fails delivery after retry policy. | event_id, endpoint_id, attempt_count |
Delivery envelope
{
"id": "evt_01hx9x9f9g7n9q6v4k0m9a2b3c",
"event": "voice.call.completed",
"created_at": "2026-05-14T18:42:09Z",
"tenant_id": "tenant_acme_dental",
"api_version": "2026-05-14",
"data": {
"call_sid": "CA1234567890abcdef1234567890abcdef",
"voice_session_id": "550e8400-e29b-41d4-a716-446655440001",
"direction": "inbound",
"status": "completed",
"duration_seconds": 127,
"escalated": false,
"summary": "Caller confirmed appointment time."
}
}Call completed payload
{
"event": "voice.call.completed",
"data": {
"stream_sid": "MZ1234567890abcdef1234567890abcdef",
"call_sid": "CA1234567890abcdef1234567890abcdef",
"from_number": "+15555555678",
"to_number": "+15555551234",
"direction": "inbound",
"status": "completed",
"duration_seconds": 142,
"escalated": false,
"function_call_count": 3,
"transcript_turn_count": 12,
"summary": "Customer asked about order status and received tracking details."
}
}Escalation payload
{
"event": "voice.call.escalated",
"data": {
"stream_sid": "MZ1234567890abcdef1234567890abcdef",
"call_sid": "CA1234567890abcdef1234567890abcdef",
"from_number": "+15555555678",
"target": "+15555559999",
"reason": "Customer requested a human agent",
"initiated_by": "ai"
}
}Delivery semantics
| Concern | Guidance |
|---|---|
| Idempotency | Store the event ID, call SID, and voice session ID. Treat duplicate deliveries as success once the event is processed. |
| Retries | Return a 2xx only after the event is durably accepted. Use quick responses and move slow business work to a queue. |
| Ordering | Do not depend on strict cross-event ordering. Reconcile final state from call logs and voice sessions when needed. |
| Security | Verify webhook signatures or shared endpoint secrets before trusting payloads. |
Replay and testing
Webhook consumers should be replay-safe. Store the event ID before executing side effects, return quickly after durable acceptance, and make downstream CRM or ticketing writes idempotent.
# Store raw payload and headers first.
# Then process from a queue keyed by event id.
event_id="evt_01hx9x9f9g7n9q6v4k0m9a2b3c"
dedupe_key="stateset-voice:${event_id}"| Test | Expected result |
|---|---|
| Send the same event twice | The second delivery is acknowledged without duplicating business work. |
Return a temporary 500 | The event remains retryable and the consumer can process the next delivery. |
| Delay downstream CRM writes | The webhook endpoint still returns quickly because slow work runs asynchronously. |
| Send an unknown event type | The consumer stores it for review and does not fail the whole endpoint. |
Event versioning policy
- New event fields are additive and should be ignored by consumers until they are needed.
- Existing event field meaning should remain stable within the documented API version.
- Breaking event changes require a new event name, version marker, or migration note in the changelog.
- Consumers should validate required fields but tolerate extra fields for forward compatibility.
Consumer checklist
- Validate the event name and expected payload fields before processing.
- Persist raw event payloads long enough for audit and replay.
- Map completed calls into CRM, ticketing, analytics, or callback queues using stable identifiers.
- Alert on delivery failure rate, consumer latency, malformed payloads, and duplicate processing attempts.