Go back to dialerseat.comsales@dialerseat.com
Voice

Voice: webhooks

Every event of every call, number and balance, signed with Ed25519, and how to verify one.


DialerSeat Voice works in the sandbox today: call it with your test key, or open Voice & SIP in the console. Live numbers and calls open by request: email dev@dialerseat.com.

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:

json
{
  "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.

Node.js
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.