Webhook Events

Receive real-time notifications about calls, recordings, voicemails, transcriptions, and faxes via HTTP webhooks.

Webhook Events is the backend transport for call events. For the browser transport, see Real-Time Events (SSE). For common patterns built on top, see Screen Pop and Activity Logging.

Overview

Webhook events are push notifications that DialStack sends to your server as things happen in the system. Unlike appointment webhooks (which are request/response), event webhooks are fire-and-forget notifications — return 200 to acknowledge receipt.

Webhook events are platform-scoped: register webhook endpoints on your platform, and DialStack delivers events for all accounts on that platform to the endpoints that match.

For frontend real-time notifications (account-scoped), see Real-Time Events (SSE).

Configuration

Register one or more webhook endpoints with the Webhook Endpoints API. Each endpoint has:

• a url that receives event POST requests,
• a secret used for signature verification (generated by DialStack and returned only in the create response — store it then, it cannot be retrieved later),
• enabled_events, the list of event types it subscribes to (defaults to ["*"], all events),
• a status (enabled or disabled).

curl https://api.dialstack.ai/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks",
    "enabled_events": ["call.answered", "call.end"]
  }'

Or with the SDK:

const endpoint = await dialstack.webhookEndpoints.create({
  url: 'https://example.com/webhooks',
  enabled_events: ['call.answered', 'call.end'], // omit for all events
});
console.log(endpoint.secret); // shown only once — store it

Test mode vs live mode

Webhook endpoints are mode-scoped, like the rest of the API. For an overview of test vs. live keys and how the two modes are isolated, see Authentication. The mode is determined by the key you create the endpoint with and is fixed for the life of the endpoint (reported as livemode on the object):

• An endpoint created with a live key (sk_live_...) receives events only from your live accounts.
• An endpoint created with a test key (sk_test_...) receives events only from your sandbox accounts.

This lets you point sandbox traffic at a separate test backend: a sandbox account's events are never delivered to a live-mode endpoint, and vice versa. If no endpoint matches an event's mode, the event is simply not delivered. Listing endpoints with a given key returns only that mode's endpoints.

Event Types

Event	Description
call.initiated	Outbound call started
call.incoming	Inbound call received
call.ringing	A user's phones are about to ring
call.mobile_push_wakeup	Send a push to wake the user's mobile app for this call
call.answered	Call answered
call.end	Call ended
call.transfer	Call transferred
call.emergency	An emergency number was dialed (911 or regional equivalent)
queue.call.queued	Caller entered a call queue
queue.call.dispatched	Queue dispatched the caller to agent targets
queue.call.answered	Queue caller was answered by an agent
queue.call.abandoned	Caller hung up while waiting in queue
queue.call.timed_out	Queue wait timed out before an agent answered
queue.call.completed	Answered queue call completed
queue.call.callback_requested	Caller requested a queue callback
queue.call.callback_attempted	Queue callback attempt completed
queue.call.callback_failed	Queue callback request reached a terminal failure
fax.received	Inbound fax received
fax.delivered	Outbound fax delivered successfully
fax.failed	Outbound fax failed to send
voicemail.new	New voicemail received
recording.available	Call recording ready for download
recording.failed	Call recording could not be prepared (e.g. redaction failed)
recording.transcription.complete	Call transcript ready
recording.summary.complete	AI call summary ready
voicemail.transcription.complete	Voicemail transcript ready
voicemail.summary.complete	AI voicemail summary ready

Event Envelope

All webhook events share this envelope structure:

{
  "id": "evt_01jqr5k8m3n4p6q7r8s9t0u1v2",
  "type": "call.end",
  "created_at": "2026-01-15T14:35:30Z",
  "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  "data": {}
}

Field	Type	Description
id	string	Unique event identifier. Use for idempotent processing.
type	string	Event type (see table above).
created_at	string	ISO 8601 timestamp when the event was created.
account_id	string	Account where the event occurred.
data	object	Event-specific payload (see below).

The SSE transport uses a different shape

The same call events are also delivered over the Real-Time Events (SSE) stream, but without this envelope: SSE payloads are flat (no id/created_at/data wrapper) and name the event-type field event rather than type. Treat the two transports as separate schemas — see the GET /v1/events reference for the authoritative SSE field names.

Event Payloads

call.initiated

Sent when an outbound call starts dialing.

{
  "id": "evt_01jqr5k8m3n4p6q7r8s9t0u1v2",
  "type": "call.initiated",
  "created_at": "2026-01-15T14:30:00Z",
  "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  "data": {
    "call_id": "call_01h2xcejqtf2nbrexx3vqjhp45",
    "direction": "outbound",
    "from_number": "+14155559876",
    "to_number": "+14155551234",
    "user_id": "user_01h2xcejqtf2nbrexx3vqjhp42",
    "from_user_id": "user_01h2xcejqtf2nbrexx3vqjhp42",
    "started_at": "2026-01-15T14:30:00Z"
  }
}

call.incoming

Sent when an inbound call is received.

{
  "id": "evt_01jqr5k8m3n4p6q7r8s9t0u1v3",
  "type": "call.incoming",
  "created_at": "2026-01-15T14:30:00Z",
  "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  "data": {
    "call_id": "call_01h2xcejqtf2nbrexx3vqjhp45",
    "direction": "inbound",
    "from_number": "+14155551234",
    "from_name": "John Smith",
    "to_number": "+14155559876",
    "user_id": "user_01h2xcejqtf2nbrexx3vqjhp42",
    "to_user_id": "user_01h2xcejqtf2nbrexx3vqjhp42",
    "started_at": "2026-01-15T14:30:00Z"
  }
}

Field	Type	Description
call_id	string	Call identifier
direction	string	Always "inbound"
from_number	string	Caller's phone number (E.164)
from_name	string | null	Caller's display name
to_number	string	Called phone number (E.164)
user_id	string | null	User the call is routed to. Only set when the called number targets a single user directly; omitted when the call routes to a ring group, voice app, dial plan, or any other destination where a specific user is not known at this stage.
from_user_id	string | null	Calling user (DIA-801). See User attribution below.
to_user_id	string | null	Called user (DIA-801). See User attribution below.
started_at	string	ISO 8601 timestamp

call.ringing

Sent when a user's phones are about to ring. Fired once per (call, user) — a user with multiple phones (desk + mobile) produces a single event, not one per device. For a ring group or ring-all-users call, one event is emitted per user being rung, all sharing the same call_id. user_id always identifies the user whose phones are ringing, never the caller.

Not emitted for the initiating user's own phone ringing during a click-to-call (leg A).

{
  "id": "evt_01jqr5k8m3n4p6q7r8s9t0u1v8",
  "type": "call.ringing",
  "created_at": "2026-01-15T14:30:01Z",
  "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  "data": {
    "call_id": "call_01h2xcejqtf2nbrexx3vqjhp45",
    "user_id": "user_01h2xcejqtf2nbrexx3vqjhp42",
    "from_number": "+14155551234",
    "from_name": "John Smith",
    "to_number": "+14155559876",
    "ringing_at": "2026-01-15T14:30:01Z"
  }
}

Field	Type	Description
call_id	string	Call identifier
user_id	string	User whose phones are about to ring
from_number	string	Caller's phone number (E.164)
from_name	string | null	Caller's display name
to_number	string	Called phone number (E.164)
ringing_at	string	ISO 8601 timestamp when the ring began

call.mobile_push_wakeup

Sent when an incoming call is being delivered to the user's web/mobile calling session and the user has mobile_push_wakeup enabled. This is your cue to send the push notification that wakes the user's mobile app: when the app has no active session, the call is held for a wake-up window while your push → app wake-up → connect flow completes.

Unlike call.ringing (which fires whenever a user is being reached, including when their calls forward to an external number), this event fires only when the user's own app session is actually being rung — every push it triggers corresponds to a real, answerable call. Use call.ringing for screen pop; use this event for mobile push delivery.

{
  "id": "evt_01jqr5k8m3n4p6q7r8s9t0u1v9",
  "type": "call.mobile_push_wakeup",
  "created_at": "2026-01-15T14:30:01Z",
  "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  "data": {
    "call_id": "call_01h2xcejqtf2nbrexx3vqjhp45",
    "user_id": "user_01h2xcejqtf2nbrexx3vqjhp42",
    "from_number": "+14155551234",
    "from_name": "John Smith",
    "to_number": "+14155559876",
    "ringing_at": "2026-01-15T14:30:01Z"
  }
}

Field	Type	Description
call_id	string	Call identifier
user_id	string	User whose app should be woken
from_number	string	Caller's phone number (E.164)
from_name	string | null	Caller's display name
to_number	string	Called phone number (E.164)
ringing_at	string	ISO 8601 timestamp when delivery began

call.answered

Sent when a call is answered.

{
  "id": "evt_01jqr5k8m3n4p6q7r8s9t0u1v4",
  "type": "call.answered",
  "created_at": "2026-01-15T14:30:05Z",
  "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  "data": {
    "call_id": "call_01h2xcejqtf2nbrexx3vqjhp45",
    "direction": "inbound",
    "from_number": "+14155551234",
    "from_name": "John Smith",
    "to_number": "+14155559876",
    "user_id": "user_01h2xcejqtf2nbrexx3vqjhp42",
    "to_user_id": "user_01h2xcejqtf2nbrexx3vqjhp42",
    "started_at": "2026-01-15T14:30:00Z",
    "answered_at": "2026-01-15T14:30:05Z",
    "connected_at": "2026-01-15T14:30:47Z"
  }
}

answered_at is the signalling answer — a greeting, menu, or voice app answering the media path counts, so for an inbound call that plays one it is roughly started_at, not when a person picked up. connected_at is when the winning leg (a user's device or an external-number fallback) answered, i.e. when live conversation began; it is null when the call is answered by voicemail. For a direct call with no greeting the two coincide.

call.end

Sent when a call ends.

{
  "id": "evt_01jqr5k8m3n4p6q7r8s9t0u1v5",
  "type": "call.end",
  "created_at": "2026-01-15T14:35:30Z",
  "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  "data": {
    "call_id": "call_01h2xcejqtf2nbrexx3vqjhp45",
    "direction": "inbound",
    "from_number": "+14155551234",
    "from_name": "John Smith",
    "to_number": "+14155559876",
    "user_id": "user_01h2xcejqtf2nbrexx3vqjhp42",
    "to_user_id": "user_01h2xcejqtf2nbrexx3vqjhp42",
    "started_at": "2026-01-15T14:30:00Z",
    "answered_at": "2026-01-15T14:30:05Z",
    "connected_at": "2026-01-15T14:30:47Z",
    "ended_at": "2026-01-15T14:35:30Z",
    "duration_seconds": 325,
    "status": "completed"
  }
}

connected_at is null when the call never connected to a person: the caller hung up during the greeting or while ringing, or the call was answered by voicemail (status: "voicemail"). This lets you distinguish a genuinely-handled call from one that only ever reached the platform.

status value	Description
completed	Call was answered and ended normally
no-answer	Call rang but was not answered
busy	Callee was busy or rejected the call
failed	Call failed due to a network or system error
voicemail	Call went to voicemail

direction value	Description
inbound	Call from PSTN to a DID
outbound	Call from an endpoint to PSTN
internal	Extension-to-extension or feature code

user_id is populated with the user most closely associated with the call: the caller for outbound; for inbound and internal, the user who answered — or, when the call ended unanswered, the single user whose phones were being rung (so a missed call is attributed to the user who missed it). It is omitted when no single user was involved — for example, an unanswered inbound ring group call, a call handled entirely by a voice app, or a dial plan call answered by a forward to an external number.

The generic call.* events are queue-agnostic; queue context is exposed via the dedicated queue.call.* events below. Subscribe to both streams and correlate by call_id when you need queue analytics alongside generic call state.

Queue call lifecycle

Queue lifecycle events are emitted in addition to the generic call.* lifecycle. Use them when you need queue-specific analytics or routing decisions without inferring queue state from call.end.

Common fields:

Field	Type	Description
call_id	string	Call identifier
queue_id	string	Queue identifier
queue_name	string	Queue display name
from_number	string	Caller's phone number (E.164)
from_name	string | null	Caller's display name
to_number	string	Called phone number (E.164)
position_at_admit	number	Caller position when admitted to the queue, omitted when unavailable
wait_seconds	number	Seconds spent waiting in queue before this outcome

Event-specific fields:

Event	Additional fields
queue.call.queued	queued_at
queue.call.dispatched	agents_claimed, targets_dispatched, dispatched_at
queue.call.answered	agent_user_id, agent_endpoint_id, answered_at
queue.call.abandoned	abandoned_at
queue.call.timed_out	timed_out_at
queue.call.completed	agent_user_id, agent_endpoint_id, completed_at
queue.call.callback_requested	callback_id, original_priority, original_entered_at, requested_at
queue.call.callback_attempted	callback_id, attempt_number, result, next_attempt_at
queue.call.callback_failed	callback_id, attempts, reason

User attribution

call.initiated, call.incoming, call.answered, and call.end also carry from_user_id and to_user_id so both sides of a call are visible — most usefully on internal user-to-user calls, where user_id alone only identifies the answerer. Both fields are omitted when the side in question is not a user on this account (for example, an external PSTN caller has no from_user_id).

Call type	from_user_id	to_user_id
Inbound PSTN → user	omitted (external caller)	The routed user
Inbound PSTN → ring group, answered	omitted	The answering member
Inbound PSTN → voice app or dial plan	omitted	omitted (until a user is rung — see below)
Inbound PSTN → user with Find Me / Follow Me	omitted	The Find Me / Follow Me owner
Outbound from an endpoint	The endpoint's user	omitted (external destination)
Internal user-to-user	The calling user	The called user
Click-to-call	The initiating user	The answering endpoint's user, when applicable

On a dial plan call, to_user_id (and user_id) track the user step currently being rung, exactly as if that user had been called directly: set while a user's phones are ringing — and kept if the caller hangs up during that ring, so the missed call is attributed to them — then replaced by the answering user when the call is answered, and cleared when the plan moves past an unanswered step or a forward to an external number answers the call. A dial plan call answered by an external number therefore carries no user_id or to_user_id.

user_id is preserved with its original semantics as a convenience alias for existing integrations; new integrations should prefer from_user_id and to_user_id.

call.transfer

Sent when a call is transferred. A transfer always involves two calls, and each one receives its own webhooks, so you can track both sides. How the second call behaves depends on the transfer type:

• Blind (cold) transfer — the caller is sent to a new destination without a consultation. This creates a brand-new call that runs its full lifecycle independently, including its own call.end when it finishes. You receive call.transfer on the original call plus a complete set of events for the new call.
• Warm (attended) transfer — you first place a consultation call to the target, then complete the transfer. On completion the consultation call is merged into the primary call rather than hung up. Because it does not end on its own, the consultation call emits call.initiated and call.answered but not call.end — its call.transfer event is its final event. The primary call continues (now connected to the transfer target) and ends normally with its own call.end.

Both calls also appear in your call logs. To relate the two calls in a transfer, use related_call, which references the other call in the pair (each call's event points at the other). It is populated whenever the two calls can be linked; if it is null, correlate them using the phone numbers and timestamps.

{
  "id": "evt_01jqr5k8m3n4p6q7r8s9t0u1v6",
  "type": "call.transfer",
  "created_at": "2026-01-15T14:32:00Z",
  "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  "data": {
    "call_id": "call_01h2xcejqtf2nbrexx3vqjhp45",
    "direction": "inbound",
    "from_number": "+14155551234",
    "to_number": "+14155559876",
    "transferred_to": "1001",
    "transferred_by": "user_01h2xcejqtf2nbrexx3vqjhp42",
    "related_call": "call_01h2xcejqtf2nbrexx3vqjhp47",
    "transferred_at": "2026-01-15T14:32:00Z"
  }
}

call.emergency

Sent when an emergency number is dialed from any endpoint on the account. Subscribers can route this event to a paging system, security desk, or any other on-call destination.

The event also fires for carrier emergency test numbers (such as 933 in the US) so you can verify your wiring end-to-end without contacting an actual public safety answering point.

e911_provisioned is false when the dialing endpoint had no provisioned dispatchable location at the time of the call. In that case location_id and location_name are omitted from the payload. Treat that combination as a signal that an emergency call went out without an accurate address — the account holder should provision the location before the next call.

e911_provisioned is omitted entirely when the emergency call was placed via a transfer. On a transfer to an emergency number the platform deliberately attaches no dispatchable location — it cannot know whether the transferring or transferred party's address is correct — and lets the public safety answering point resolve the location. The field has no meaning in that case, so its absence (rather than false) distinguishes a transfer from an unprovisioned direct call.

{
  "id": "evt_01jqr5k8m3n4p6q7r8s9t0u1v8",
  "type": "call.emergency",
  "created_at": "2026-05-03T18:30:00Z",
  "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  "data": {
    "call_id": "call_01h2xcejqtf2nbrexx3vqjhp45",
    "to_number": "911",
    "user_id": "user_01h2xcejqtf2nbrexx3vqjhp47",
    "device_id": "dev_01h2xcejqtf2nbrexx3vqjhp49",
    "extension": "1001",
    "location_id": "loc_01h2xcejqtf2nbrexx3vqjhp48",
    "location_name": "Headquarters",
    "location_address": "123 Main St, Springfield, IL 62701, US",
    "e911_provisioned": true,
    "placed_at": "2026-05-03T18:30:00Z"
  }
}

voicemail.new

Sent when a new voicemail is received. Use GET /v1/voicemails/{voicemail_id} to retrieve the full voicemail details and audio.

{
  "id": "evt_01jqr5k8m3n4p6q7r8s9t0u1v7",
  "type": "voicemail.new",
  "created_at": "2026-01-15T14:36:00Z",
  "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  "data": {
    "voicemail_id": "vm_01h2xcejqtf2nbrexx3vqjhp46",
    "user_id": "user_01h2xcejqtf2nbrexx3vqjhp42",
    "call_id": "call_01h2xcejqtf2nbrexx3vqjhp45",
    "from_number": "+14155551234",
    "from_name": "John Smith",
    "duration_seconds": 42,
    "created_at": "2026-01-15T14:36:00Z"
  }
}

user_id is included when the voicemail belongs to a single user's mailbox and is omitted when it belongs to a shared voicemail box. call_id identifies the call that produced the voicemail — use it to correlate with GET /v1/calls/{call_id} — and is omitted when the call could not be resolved.

recording.available

Sent when a call recording is ready for download. Use GET /v1/calls/{call_id}/recording to download the audio file.

{
  "id": "evt_01jqr5k8m3n4p6q7r8s9t0u1v8",
  "type": "recording.available",
  "created_at": "2026-01-15T14:35:35Z",
  "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  "data": {
    "call_id": "call_01h2xcejqtf2nbrexx3vqjhp45",
    "duration_seconds": 325
  }
}

recording.failed

Sent when a call recording could not be prepared and will never become available. On accounts with PII redaction enabled, recording.available is withheld until redaction succeeds; if redaction cannot complete, the audio is discarded and this event is sent instead so you are not left waiting for a recording that will never arrive. No recording is retrievable for the call.

{
  "id": "evt_01jqr5k8m3n4p6q7r8s9t0u1w0",
  "type": "recording.failed",
  "created_at": "2026-01-15T14:35:40Z",
  "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  "data": {
    "call_id": "call_01h2xcejqtf2nbrexx3vqjhp45",
    "error_code": "audio_redaction_failed",
    "reason": "audio could not be redacted"
  }
}

Branch on error_code, not the free-form reason:

error_code	Meaning
audio_redaction_failed	The audio could not be redacted (unreadable recording, or sensitive speech that could not be located in the audio)
transcription_failed	The call could not be transcribed, so sensitive speech could not be found
internal_error	An internal error prevented the recording from being processed

reason is an optional human-readable sentence for logging; new codes may be added, so treat an unrecognized error_code as a generic failure.

recording.transcription.complete

Sent when a call transcription is ready. Use GET /v1/calls/{call_id}/transcript to retrieve the full transcript text.

{
  "id": "evt_01jqr5k8m3n4p6q7r8s9t0u1v9",
  "type": "recording.transcription.complete",
  "created_at": "2026-01-15T14:35:45Z",
  "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  "data": {
    "call_id": "call_01h2xcejqtf2nbrexx3vqjhp45",
    "status": "completed"
  }
}

recording.summary.complete

Sent when an AI-generated call summary is ready. Use GET /v1/calls/{call_id}/transcript to retrieve the summary.

{
  "id": "evt_01jqr5k8m3n4p6q7r8s9t0u1va",
  "type": "recording.summary.complete",
  "created_at": "2026-01-15T14:36:00Z",
  "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  "data": {
    "call_id": "call_01h2xcejqtf2nbrexx3vqjhp45"
  }
}

voicemail.transcription.complete

Sent when a voicemail transcription is ready. Use GET /v1/voicemails/{voicemail_id}/transcript to retrieve the transcript text.

{
  "id": "evt_01jqr5k8m3n4p6q7r8s9t0u1vb",
  "type": "voicemail.transcription.complete",
  "created_at": "2026-01-15T14:36:10Z",
  "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  "data": {
    "voicemail_id": "vm_01h2xcejqtf2nbrexx3vqjhp46",
    "user_id": "user_01h2xcejqtf2nbrexx3vqjhp42",
    "call_id": "call_01h2xcejqtf2nbrexx3vqjhp45",
    "status": "completed"
  }
}

call_id identifies the call that produced the voicemail and is omitted when the call could not be resolved.

voicemail.summary.complete

Sent when an AI-generated voicemail summary is ready. Use GET /v1/voicemails/{voicemail_id} to retrieve the summary.

{
  "id": "evt_01jqr5k8m3n4p6q7r8s9t0u1vc",
  "type": "voicemail.summary.complete",
  "created_at": "2026-01-15T14:36:20Z",
  "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  "data": {
    "voicemail_id": "vm_01h2xcejqtf2nbrexx3vqjhp46",
    "user_id": "user_01h2xcejqtf2nbrexx3vqjhp42",
    "call_id": "call_01h2xcejqtf2nbrexx3vqjhp45"
  }
}

call_id identifies the call that produced the voicemail and is omitted when the call could not be resolved.

Fax events

The three fax events share a payload shape so a single fax.* handler can process all of them. fax.received is an inbound event; fax.delivered and fax.failed are outbound outcomes. They are terminal — a fax produces exactly one of fax.delivered or fax.failed, never both, and there are no intermediate queued/sending events.

Common fields:

Field	Type	Description
fax_id	string	Fax identifier. Use GET /v1/faxes/{fax_id} for full details
from_number	string	Sending fax number (E.164)
to_number	string	Receiving fax number (E.164)
pages	number | null	Pages transmitted (see per-event notes)
transport	string | null	Negotiated fax transport: "t38" (fax over IP) or "g711" (fax over audio)

The transport value reflects how the fax was carried, not whether it succeeded — read fax.delivered vs fax.failed for the outcome. It is always present on fax.received; on the outbound events it is null when the call ended before a transport was negotiated.

fax.received

Sent when an inbound fax has been fully received and converted. pages and transport are always present.

{
  "id": "evt_01jqr5k8m3n4p6q7r8s9t0u1vd",
  "type": "fax.received",
  "created_at": "2026-01-15T14:40:00Z",
  "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  "data": {
    "fax_id": "fax_01h2xcejqtf2nbrexx3vqjhp4a",
    "from_number": "+14155551234",
    "to_number": "+14155559876",
    "pages": 3,
    "transport": "t38"
  }
}

fax.delivered

Sent when an outbound fax completed successfully — the receiving machine confirmed the full document. pages is the number of pages confirmed delivered.

{
  "id": "evt_01jqr5k8m3n4p6q7r8s9t0u1ve",
  "type": "fax.delivered",
  "created_at": "2026-01-15T14:42:00Z",
  "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  "data": {
    "fax_id": "fax_01h2xcejqtf2nbrexx3vqjhp4b",
    "from_number": "+14155559876",
    "to_number": "+14155551234",
    "pages": 2,
    "transport": "t38"
  }
}

fax.failed

Sent when an outbound fax did not complete. Carries an error_code in addition to the common fields.

{
  "id": "evt_01jqr5k8m3n4p6q7r8s9t0u1vf",
  "type": "fax.failed",
  "created_at": "2026-01-15T14:44:00Z",
  "account_id": "acct_01h2xcejqtf2nbrexx3vqjhp41",
  "data": {
    "fax_id": "fax_01h2xcejqtf2nbrexx3vqjhp4c",
    "from_number": "+14155559876",
    "to_number": "+14155551234",
    "pages": null,
    "transport": null,
    "error_code": "max_attempts_exceeded"
  }
}

Field	Type	Description
error_code	string | null	A short code for why the fax failed — e.g. dial_busy, dial_no_answer, max_attempts_exceeded, fax_failed. null when no code was determined
pages	number | null	null when the page count is unknown (the fax never began transmitting); 0 when it connected but failed before the first page; N when N pages were sent before failing
transport	string | null	null when the call failed before a transport was negotiated

fax.delivered and fax.failed are mutually exclusive and final. A fax.delivered means the receiving machine acknowledged the whole document; a fax.failed means it did not, after all automatic retries.

Webhook Protocol

Request Format

DialStack sends a POST request to each matching endpoint's url with the event as the JSON body. An event is delivered to an endpoint only when the endpoint's mode matches the originating account's mode and its enabled_events includes the event type (or is ["*"]).

Headers:

Header	Description
Content-Type	application/json
X-DialStack-Signature	HMAC-SHA256 signature for verification
X-DialStack-Account-Id	Account where the event occurred
User-Agent	DialStack-Webhook/1.0

Signature Verification

Every webhook request is signed using HMAC-SHA256 with the receiving endpoint's secret. Each endpoint has its own secret, so verify against the secret of the endpoint that received the request. The signature header format is:

X-DialStack-Signature: t=1705312530,v1=a1b2c3d4e5f6...

To verify:

1. Extract the timestamp (t) and signature (v1) from the header
2. Construct the signed payload: {timestamp}.{request_body}
3. Compute HMAC-SHA256 of the signed payload using your webhook secret
4. Compare with the provided signature

For detailed verification examples in Node.js, Python, and Go, see Appointment Webhooks — Signature Verification.

Expected Response

Return any 2xx status code to acknowledge receipt. The response body is ignored. Non-2xx responses trigger a retry.

Retry Behavior

Failed deliveries (non-2xx response or timeout) are retried automatically:

• Up to 5 retry attempts at approximately 60-second intervals
• 30-second timeout per delivery attempt
• After all retries are exhausted, the event is moved to a dead letter queue for investigation

When an account has multiple matching endpoints, a retry re-delivers the event to all of them, so an endpoint that already responded 2xx may receive the event again. Combined with at-least-once delivery, this is why you should handle events idempotently using the id field.

Ordering

Events for the same account are delivered in order. Events for different accounts may be delivered in parallel. Do not assume ordering across accounts.

Timing

Event	Typical Latency
call.initiated	< 1 second
call.incoming	< 1 second
call.ringing	< 1 second
call.mobile_push_wakeup	< 1 second
call.answered	< 1 second
call.end	< 1 second
call.transfer	< 1 second
queue.call.*	< 1 second
voicemail.new	< 2 seconds
recording.available	< 5 seconds after call ends; on redaction-enabled accounts, after redaction completes (transcription + audio rewrite)
recording.failed	On redaction-enabled accounts, when redaction cannot complete
recording.transcription.complete	~10 seconds after recording
recording.summary.complete	~15 seconds after recording
voicemail.transcription.complete	~10 seconds after voicemail
voicemail.summary.complete	~15 seconds after voicemail
fax.received	< 1 second after receipt completes
fax.delivered	< 1 second after transmission completes
fax.failed	< 1 second after the final attempt

Best Practices

• Verify signatures on every request to prevent spoofing
• Return 200 quickly and defer processing — long-running handlers risk timeouts
• Handle events idempotently using the id field — events may be delivered more than once
• Don't rely on strict cross-account ordering — events from different accounts may arrive in any order

Related Resources

• Real-Time Events (SSE) — Frontend event streaming
• Appointment Webhooks — Scheduling webhook protocol
• Voice Apps — Programmable voice webhooks