Voice: webhooks
Every event of every call, number and balance, signed with Ed25519, and how to verify one.
Events go to the webhook URL of the connection or application that owns the call, or the webhook_url you set on a dial. Each is a POST with this shape:
{
"data": {
"record_type": "event",
"id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
"event_type": "call.answered",
"occurred_at": "2026-11-16T15:04:05.000Z",
"payload": { "call_control_id": "v3:...", "from": "+12145550100", "to": "+15125550142", "direction": "outbound", "client_state": "bGVhZDo0Mg==" }
},
"meta": { "attempt": 1, "delivered_to": "https://crm.example.com/voice/events" }
}Verifying a webhook
Each delivery has DialerSeat-Signature-Ed25519 (a base64 signature of the timestamp, a pipe, and the raw body) and DialerSeat-Timestamp (unix seconds). Verify with your public key from GET /v1/voice/public_key and refuse anything more than five minutes old. Read the raw body: re-serialized JSON will not verify.
import crypto from 'node:crypto'
// Your public key from GET /v1/voice/public_key (32 bytes, base64).
const PUBLIC_KEY = crypto.createPublicKey({
key: Buffer.concat([Buffer.from('302a300506032b6570032100', 'hex'), Buffer.from(process.env.DS_VOICE_PUBLIC_KEY, 'base64')]),
format: 'der', type: 'spki',
})
export function verify(rawBody, signature, timestamp) {
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
return crypto.verify(null, Buffer.from(`${timestamp}|${rawBody}`), PUBLIC_KEY, Buffer.from(signature, 'base64'))
}
// In your handler: verify(rawBody, req.headers['dialerseat-signature-ed25519'], req.headers['dialerseat-timestamp'])Events
call.initiated: A call started: one you placed, or one ringing your number.call.answered: The far end picked up.call.bridged: Two calls were connected, by bridge or by bridge_on_answer.call.hangup: The call ended, with the cause, the SIP code and who hung up.call.cost: What the call cost, after it ended: billed seconds, rate and amount.call.machine.detection.ended: Standard detection finished: human, machine or not_sure.call.machine.greeting.ended: A machine's greeting ended: beep_detected, ended or not_sure. The moment to leave a message.call.machine.premium.detection.ended: Premium detection finished: human_residence, human_business, machine, silence or fax_detected.call.machine.premium.greeting.ended: Premium detection heard the beep: beep_detected or no_beep_detected.call.speak.started: Speech started playing.call.speak.ended: Speech finished.call.playback.started: Audio started playing.call.playback.ended: Audio finished or was stopped.call.gather.ended: A gather finished, with the digits and why it ended.call.dtmf.received: The caller pressed a key.call.recording.saved: A recording was saved, with its download link.streaming.started: Audio began streaming to your WebSocket.streaming.stopped: The stream ended.conference.created: A conference started.conference.participant.joined: A call joined a room.conference.participant.left: A call left a room.conference.ended: The room closed.- number_order.completed: Numbers you bought can take calls.
- porting_order.status_changed: A port moved a step: submitted, exception, confirmed, completed or canceled.
balance.low: Your balance fell under your low-balance threshold.balance.recharged: Auto-recharge topped your balance up.
Every event has an id that stays the same on a retry; process each id once. GET /v1/voice/call_events lists everything sent for a call and what your server answered.
Related:DialerSeat Voice: numbers, SIP and a voice API, Voice: numbers, porting and 911, Voice: SIP trunking and Voice: the Voice API.