Developers / WebhooksAll pages
Developers

Webhooks

Your systems learn about calls, voicemail, queues, AI analysis and tickets the moment they happen. Every request is signed, so you can prove it came from your phone system, and retried if your server is down.

Event types
16, plus ping
Signature
HMAC-SHA256
Timeout
10 seconds
Attempts
Up to 8 in about an hour

How it works

Events come from two places. Calls, queues and voicemail are picked up by the dashboard's background worker, which looks for new call records every 5 seconds. Everything people do in the dashboard (tags, notes, tickets, status) and the results of transcription and analysis are queued the moment they happen. Either way the event is written to a delivery queue in the database, one delivery per endpoint, and the worker sends it.

Your Voip9 serverworkerat oncewhen doneduePOSTCalls & queuesCall records · queue logDashboard actionsTags · tickets · statusAnalysis jobsTranscripts · AIDelivery queueMariaDBWorkerEvery 5 s · signsYour endpointHTTPS
Every event goes through the delivery queue, so nothing is lost if your server is briefly down.

Only one dashboard process, the leader, detects call events and sends webhooks, so an event is never sent twice by two servers. When the worker first starts it begins at "now": it never replays old call history.

Setting up

  1. Add an endpoint

    In the dashboard: Administration → Integrations → Webhooks → Add endpoint. Enter the URL, an optional description, and pick the events, or All events (which also includes event types added in later versions).

  2. Copy the signing secret

    The secret (whsec_…) is shown once. Store it next to your receiver. New signing secret replaces it immediately: the old one stops working at once, including for retries that are still pending.

  3. Send a test event

    Send test event queues a ping to that endpoint; it arrives within a few seconds. Check that your code accepts the signature and answers 2xx, then watch the delivery appear under Deliveries.

Which URLs are allowed

  • The URL must be https:// and must not contain a user name or password; put credentials in your endpoint, not in the URL.
  • The host must resolve to a public address. Loopback, private networks (10/8, 172.16/12, 192.168/16, 100.64/10), link-local and cloud metadata (169.254.x.x), IPv6 local addresses and multicast are refused. The check runs when you save and again before every attempt.
  • On-premises installations that post to internal systems can set WEBHOOK_ALLOW_PRIVATE=yes in the dashboard's environment. That turns the address check off and also allows http://.

The request

Every delivery is a POST with a JSON body. The body is the same for every attempt; only the timestamp and signature headers change.

A deliveryHTTP
1POST /voip9/events HTTP/1.12Host: hooks.yourbank.example3Content-Type: application/json4User-Agent: Voip9-Webhooks/1.05X-Voip9-Event: call.completed6X-Voip9-Delivery: evt_5c0e2a9b41d7f3e8a1b2c3d47X-Voip9-Timestamp: 17946788008X-Voip9-Signature: v1=4f1c9b0e…e9a29 10{11  "id": "evt_5c0e2a9b41d7f3e8a1b2c3d4",12  "type": "call.completed",13  "created_at": "2026-11-14T17:53:20.512Z",14  "organization": "sunrisemb",15  "data": { "call_id": "1794678793.33", "direction": "inbound", "status": "answered", "…": "…" }16}

Headers

X-Voip9-Eventstring
The event type, same as body.type.
X-Voip9-Deliverystring
The event id, same as body.id. Stays the same on every retry: use it to ignore duplicates.
X-Voip9-Timestampinteger
Unix time in seconds when this attempt was sent.
X-Voip9-Signaturestring
v1= followed by the hex HMAC-SHA256 of {timestamp}.{raw body}, keyed with your signing secret.
User-Agentstring
Voip9-Webhooks/1.0

Body

idstring
Event id, evt_ and 24 hex characters. The same event sent to two endpoints has the same id.
typestring
The event type.
created_atstring
When the event was created, ISO 8601 UTC. Use this, not arrival time, to order events.
organizationstring
The organization's id (slug) the event belongs to.
dataobject
The event's fields, listed under Event reference.

Verifying the signature

Compute the HMAC over the raw request body, before any JSON parsing, using the whole secret including its whsec_ prefix as the key. Compare in constant time, and reject requests whose timestamp is more than 5 minutes from your clock.

What is signedText
signature = "v1=" + hex( HMAC_SHA256( key = signing secret, message = X-Voip9-Timestamp + "." + raw body ) )
server.js (Express)JavaScript
1import crypto from "node:crypto"2import express from "express"3 4const SECRET = process.env.VOIP9_WEBHOOK_SECRET // whsec_… (the whole string is the key)5const app = express()6 7// keep the RAW body: the signature covers the exact bytes that were sent8app.post("/voip9/events", express.raw({ type: "application/json" }), (req, res) => {9  const ts = req.header("X-Voip9-Timestamp") ?? ""10  const sig = req.header("X-Voip9-Signature") ?? ""11  const expected = "v1=" + crypto.createHmac("sha256", SECRET).update(`${ts}.`).update(req.body).digest("hex")12 13  const ok = sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))14  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300 // reject replays older than 5 minutes15  if (!ok || !fresh) return res.sendStatus(401)16 17  const event = JSON.parse(req.body.toString("utf8"))18  // event.id stays the same on every retry: ignore one you already processed19  queueForProcessing(event)20  res.sendStatus(200) // answer within 10 seconds, do the slow work afterwards21})22 23app.listen(8080)

Responding

  • Answer with any 2xx status within 10 seconds. The body of your answer is ignored.
  • Anything else is a failed attempt: another status, a timeout, a connection error or a redirect. Redirects are never followed.
  • Do the slow work (CRM updates, emails) after you answer, from your own queue.

Retries and backoff

A failed attempt is tried again later, waiting twice as long each time, up to 8 attempts per event and endpoint. After the eighth failure the delivery is marked failed and is not tried again unless someone sends it again from the dashboard.

AttemptSentTime since the first attempt
1As soon as the event is queued0
230 s after attempt 1 failsabout 30 s
31 min laterabout 1.5 min
42 min laterabout 3.5 min
54 min laterabout 7.5 min
68 min laterabout 15.5 min
716 min laterabout 31.5 min
832 min later, the last attemptabout 63.5 min

The worker runs every 5 seconds, so each attempt can go out up to a few seconds after its time. An attempt that is skipped because the URL no longer passes the address check counts as a failed attempt too.

Phone systemPhone systemDelivery queueDelivery queueWorkerWorkerYour endpointYour endpointcall endedcall.completed queued1due nowattempt 12POST (signed, ts=…800)X-Voip9-Delivery: evt_5c0e…3503 / timeout after 10 s4pending, next in 30 sattempts = 1530 seconds laterdue againattempt 27POST (signed, ts=…833)same id, same body8200 OK9deliveredcode 200 kept for 30 days10
A delivery that fails once and succeeds on the retry. The event id stays the same; the timestamp and signature are new.

Idempotency and ordering

Expect each event at least once, not exactly once. If your server processed an event but answered too slowly, it will receive the same event again. Use the event id (also in X-Voip9-Delivery) as a unique key and ignore ids you have already handled.

Ignore duplicatesJavaScript
1// Postgres: a table with the event id as primary key makes duplicates harmless2//   CREATE TABLE voip9_events (id text PRIMARY KEY, type text, received_at timestamptz DEFAULT now());3async function queueForProcessing(event) {4  const { rowCount } = await db.query("INSERT INTO voip9_events (id, type) VALUES ($1, $2) ON CONFLICT (id) DO NOTHING", [event.id, event.type])5  if (rowCount === 0) return // already handled: a retry of something we answered too slowly6  await jobs.add(event.type, event) // process later, outside the HTTP request7}
  • Deliveries go out oldest first, but a retry can arrive after newer events. Order by created_at, not by arrival.
  • One action can produce several events: an unanswered call sends call.completed and call.missed; a recorded call later sends transcript.ready, then call.analyzed and possibly keyword.detected.
  • Join them with call_id (call events) or recording (transcript and analysis events). call.completed carries both.

Testing and redelivery

  • Send test event on an endpoint queues a ping for that endpoint only. It must be enabled.
  • Deliveries lists recent deliveries with the event, endpoint, status (Delivered, Pending, Failed), your response code or the error, and the number of attempts.
  • Send again on a delivered or failed delivery queues it again with a fresh set of 8 attempts. It is the same event with the same id, so your duplicate check will skip it if you already processed it; delete that id on your side first if you want it processed again.
  • Delivery history is kept for 30 days; pending deliveries are never removed.

Event reference

The fields below are the data object of the envelope. New fields may be added to an event; ignore fields you do not know.

EventSent when
call.completedEvery call that ended, in any direction and with any outcome. Sent a few seconds after the last leg hangs up.
call.missedSent in addition to call.completed for inbound and internal calls whose status is missed, voicemail or busy. Same fields. Subscribe to this one alone if you only care about callers nobody spoke to.
voicemail.receivedA caller left a voicemail in a person's mailbox.
queue.abandonedThe caller hung up while waiting in a queue.
queue.timeoutThe caller waited the queue's maximum time and was sent to its fallback. Same fields as queue.abandoned.
transcript.readyA recorded call was transcribed, either by call analysis or because someone opened its transcript in the dashboard. Caller and agent are transcribed separately. When the transcript was opened by hand, only recording and utterances are present.
call.analyzedThe AI analysis of a recorded call is ready. Needs call analysis turned on for the organization.
keyword.detectedOne of the organization's watched keywords (Insights → Watched keywords) was said on an analysed call. Matching is case-insensitive, on whole words or phrases.
call.taggedSomeone changed the tags of a call in the call details panel. Tags come from the organization's own list; a call has at most 10.
call.commentedSomeone wrote or changed the note on a call. Same fields as call.tagged, with note instead of tags.
user.status_changedA person changed their own availability in the dashboard. Anything but available pauses them in every queue. Changes made through the REST API do not send this event.
call.callback_requestedA caller chose to be called back in an IVR menu (the Offer a callback block). The same request appears in the team's Inbox.
message.receivedA message arrived on one of your channels (WhatsApp or a bridged provider). The thread is in Conversations. A duplicate delivery from the provider is not sent twice.
ticket.createdA support ticket was created.
ticket.updatedA ticket changed. There are two shapes: an edit (status, priority, team, assignee, title, customer) carries changed and by; linking calls or conversations carries "change": "linked" and the links that were added.
ticket.resolvedA ticket's status became resolved or closed. Sent instead of ticket.updated for that save, with the same edit fields.
pingSent only by Send test event, to that one endpoint, whatever events it subscribes to. Use it to check your signature code.

Calls

call.completed

Every call that ended, in any direction and with any outcome. Sent a few seconds after the last leg hangs up.

call_idstring
The call's id (Asterisk linked id), unique per call. Same as call_id in the REST API.
directionstring
inbound (from a carrier), outbound (to an outside number) or internal.
fromstring
The calling number or extension.
tostring
What was dialled: an extension, IVR, queue or outside number.
statusstring
answered, missed, voicemail, busy, failed, or ai_agent (handled by the AI voice agent).
started_atstring
ISO 8601, UTC.
duration_secondsinteger
Ringing plus talking.
talk_secondsinteger
Talking only.
answered_bystring | null
The extension that answered, or null.
recordingstring | null
The recording's name, or null when the call was not recorded. The same value appears as recording in transcript and analysis events.
missed_reasonstring | null
For calls nobody answered: short_abandoned (hung up within 10 s), abandoned_in_ivr, abandoned_in_queue, queue_timeout, no_available_agent, agents_did_not_answer, busy, voicemail, failed. Null for answered and outbound calls.
call.completed · dataJSON
1{2  "call_id": "1794678793.33",3  "direction": "inbound",4  "from": "+923001234567",5  "to": "8101",6  "status": "answered",7  "started_at": "2026-11-14T17:53:13.000Z",8  "duration_seconds": 64,9  "talk_seconds": 51,10  "answered_by": "1004",11  "recording": "20261114-175313-1-1794678793.33",12  "missed_reason": null13}

call.missed

Sent in addition to call.completed for inbound and internal calls whose status is missed, voicemail or busy. Same fields. Subscribe to this one alone if you only care about callers nobody spoke to.

call.missed · dataJSON
1{2  "call_id": "1794679120.41",3  "direction": "inbound",4  "from": "+923001234567",5  "to": "8201",6  "status": "missed",7  "started_at": "2026-11-14T17:58:40.000Z",8  "duration_seconds": 95,9  "talk_seconds": 0,10  "answered_by": null,11  "recording": null,12  "missed_reason": "abandoned_in_queue"13}

voicemail.received

A caller left a voicemail in a person's mailbox.

mailboxstring
The extension whose mailbox it is.
fromstring
The caller ID as received, name and number, e.g. "Ali Raza" <+923001234567>.
duration_secondsinteger
Length of the message.
received_atstring
ISO 8601, UTC.
message_idstring
The message id; the same as id in GET /api/v1/voicemail.
voicemail.received · dataJSON
1{2  "mailbox": "1004",3  "from": "\"Ali Raza\" <+923001234567>",4  "duration_seconds": 18,5  "received_at": "2026-11-14T18:02:40.000Z",6  "message_id": "1794680560-00000003"7}

queue.abandoned

The caller hung up while waiting in a queue.

queuestring
The queue number (82xx).
callerstring | null
The caller's number, when known.
waited_secondsinteger
How long they waited.
positioninteger | null
Their place in the line when they left.
atstring
ISO 8601, UTC.
queue.abandoned · dataJSON
1{2  "queue": "8201",3  "caller": "+923001234567",4  "waited_seconds": 95,5  "position": 2,6  "at": "2026-11-14T18:04:11.000Z"7}

queue.timeout

The caller waited the queue's maximum time and was sent to its fallback. Same fields as queue.abandoned.

queue.timeout · dataJSON
{ "queue": "8201", "caller": "+923001234567", "waited_seconds": 300, "position": 1, "at": "2026-11-14T18:09:00.000Z" }

call.callback_requested

A caller chose to be called back in an IVR menu (the Offer a callback block). The same request appears in the team's Inbox.

call_idstring
The call the request was made on.
fromstring
The number to call back.
ivrstring
The IVR menu's number (81xx).
blockstring
The block's label in the IVR builder.
requested_atstring
ISO 8601, UTC.
call.callback_requested · dataJSON
{ "call_id": "1794678793.33", "from": "+923001234567", "ivr": "8101", "block": "Offer a callback", "requested_at": "2026-11-15T09:12:40.000Z" }

Transcripts and AI analysis

transcript.ready

A recorded call was transcribed, either by call analysis or because someone opened its transcript in the dashboard. Caller and agent are transcribed separately. When the transcript was opened by hand, only recording and utterances are present.

recordingstring
The recording's name; matches recording in call.completed.
call_datestring
When the call started, UTC YYYY-MM-DD HH:MM:SS. Only when sent by call analysis.
fromstring
The calling number. Only when sent by call analysis.
tostring
The dialled number. Only when sent by call analysis.
utterancesarray
Each line: side (caller or callee), start and end in seconds, text.
transcript.ready · dataJSON
1{2  "recording": "20261114-175313-1-1794678793.33",3  "call_date": "2026-11-14 17:53:13",4  "from": "+923001234567",5  "to": "8201",6  "utterances": [7    { "side": "caller", "start": 0.4, "end": 3.1, "text": "Hi, my card was blocked this morning." },8    { "side": "callee", "start": 3.5, "end": 6.0, "text": "I can help with that. Can you confirm your name?" }9  ]10}

call.analyzed

The AI analysis of a recorded call is ready. Needs call analysis turned on for the organization.

recordingstring
The recording's name; matches recording in call.completed.
call_datestring
When the call started, UTC YYYY-MM-DD HH:MM:SS.
fromstring
The calling number.
tostring
The dialled number.
summarystring
At most two sentences, up to 600 characters.
intentstring
The caller's reason in a few words.
topicsstring[]
1 to 3 short lowercase topics.
sentimentstring
The caller's mood at the end: positive, neutral or negative.
urgencystring
low, medium or high.
flagsstring[]
Any of complaint, fraud, emergency, cancellation, escalation, technical_issue, compliment.
call.analyzed · dataJSON
1{2  "recording": "20261114-175313-1-1794678793.33",3  "call_date": "2026-11-14 17:53:13",4  "from": "+923001234567",5  "to": "8201",6  "summary": "Caller's debit card was blocked after a failed PIN; the agent unblocked it after verification.",7  "intent": "unblock debit card",8  "topics": ["card blocked", "pin reset"],9  "sentiment": "positive",10  "urgency": "medium",11  "flags": []12}

keyword.detected

One of the organization's watched keywords (Insights → Watched keywords) was said on an analysed call. Matching is case-insensitive, on whole words or phrases.

recordingstring
The recording's name; matches recording in call.completed.
call_datestring
When the call started, UTC YYYY-MM-DD HH:MM:SS.
fromstring
The calling number.
tostring
The dialled number.
keywordsarray
One entry per keyword found: word, side (caller or callee) and quote, the first line it was said in (up to 200 characters).
keyword.detected · dataJSON
1{2  "recording": "20261114-175313-1-1794678793.33",3  "call_date": "2026-11-14 17:53:13",4  "from": "+923001234567",5  "to": "8201",6  "keywords": [7    { "word": "fraud", "side": "caller", "quote": "I think this is fraud, I never made that payment." }8  ]9}

People and follow-up

call.tagged

Someone changed the tags of a call in the call details panel. Tags come from the organization's own list; a call has at most 10.

call_idstring
The call.
fromstring
The calling number.
tostring
The dialled number.
bystring
Email of the person who made the change.
tagsstring[]
The call's tags after the change (the full list, not the difference).
call.tagged · dataJSON
{ "call_id": "1794678793.33", "from": "+923001234567", "to": "8201", "by": "agent@yourbank.com", "tags": ["card blocked", "resolved"] }

call.commented

Someone wrote or changed the note on a call. Same fields as call.tagged, with note instead of tags.

notestring
The whole note after the change, up to 2,000 characters. Empty when it was cleared.
call.commented · dataJSON
{ "call_id": "1794678793.33", "from": "+923001234567", "to": "8201", "by": "agent@yourbank.com", "note": "Unblocked after ID check" }

user.status_changed

A person changed their own availability in the dashboard. Anything but available pauses them in every queue. Changes made through the REST API do not send this event.

extensionstring
The person's extension.
namestring
Their name.
statusstring
available, break, lunch, training, back_office or dnd.
atstring
ISO 8601, UTC.
user.status_changed · dataJSON
{ "extension": "1004", "name": "Sara Ahmed", "status": "lunch", "at": "2026-11-14T13:02:11.000Z" }

message.received

A message arrived on one of your channels (WhatsApp or a bridged provider). The thread is in Conversations. A duplicate delivery from the provider is not sent twice.

conversation_idinteger
The conversation in the dashboard.
channelstring
The channel's name as set by your Admin.
fromstring
The sender's number or id on that channel.
namestring
The sender's name, when the channel gives one.
kindstring
text, image, audio, document, location or other.
textstring
The message text; empty for media without a caption.
received_atstring
ISO 8601, UTC.
message.received · dataJSON
{ "conversation_id": 12, "channel": "WhatsApp · Card services", "from": "+923001234567", "name": "Ali Khan", "kind": "text", "text": "My card is blocked", "received_at": "2026-11-15T10:02:11.000Z" }

ticket.created

A support ticket was created.

idinteger
The ticket's id.
numberinteger
The ticket number people see (#42).
titlestring
Short title.
teamstring
The team it is assigned to, empty for none.
statusstring
open, pending, resolved or closed.
prioritystring
low, normal, high or urgent.
assigneestring | null
Extension of the person it is assigned to.
customerstring
The customer's phone number, empty when not set.
created_bystring
Email of the person who created it.
linksarray
What it was created from: { "kind": "call", "ref": "<call_id>" } or { "kind": "conversation", "ref": "<id>" }.
ticket.created · dataJSON
1{2  "id": 7,3  "number": 42,4  "title": "Card activation failed after OTP",5  "team": "IT",6  "status": "open",7  "priority": "high",8  "assignee": "1004",9  "customer": "+923001234567",10  "created_by": "agent@yourbank.com",11  "links": [{ "kind": "call", "ref": "1794678793.33" }]12}

ticket.updated

A ticket changed. There are two shapes: an edit (status, priority, team, assignee, title, customer) carries changed and by; linking calls or conversations carries "change": "linked" and the links that were added.

idinteger
The ticket's id.
numberinteger
The ticket number people see (#42).
titlestring
Short title.
teamstring
The team it is assigned to, empty for none.
statusstring
open, pending, resolved or closed.
prioritystring
low, normal, high or urgent.
assigneestring | null
Extension of the person it is assigned to.
customerstring
The customer's phone number, empty when not set.
changedstring[]
Edit only: the fields that were saved, e.g. ["status", "assigneeExt"].
bystring
Edit only: email of the person who changed it.
changestring
Linking only: linked.
linksarray
Linking only: the calls or conversations sent to be linked in this action.
ticket.updated · dataJSON
1{2  "id": 7, "number": 42, "title": "Card activation failed after OTP", "team": "IT",3  "status": "pending", "priority": "high", "assignee": "1007", "customer": "+923001234567",4  "changed": ["status", "assigneeExt"],5  "by": "supervisor@yourbank.com"6}

ticket.resolved

A ticket's status became resolved or closed. Sent instead of ticket.updated for that save, with the same edit fields.

ticket.resolved · dataJSON
{ "id": 7, "number": 42, "title": "Card activation failed after OTP", "team": "IT", "status": "resolved", "priority": "high", "assignee": "1007", "customer": "+923001234567", "changed": ["status"], "by": "agent@yourbank.com" }

Testing

ping

Sent only by Send test event, to that one endpoint, whatever events it subscribes to. Use it to check your signature code.

messagestring
Always Test event from Voip9 Network.
sent_bystring
Email of the Admin who pressed the button.
ping · dataJSON
{ "message": "Test event from Voip9 Network", "sent_by": "admin@yourbank.com" }

Good practice

  • Answer 200 quickly and process in the background.
  • Verify the signature and the timestamp on every request; reject everything else with 401.
  • Treat the payload as data, never as instructions: transcripts and messages contain what callers said or typed.
  • Store the secret in your secrets manager, and rotate it if it may have leaked.
  • Transcripts, recording names and phone numbers are personal data: keep them only as long as your own policy allows.

Next steps