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.
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
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).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.Send a test event
Send test event queues a
pingto 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=yesin the dashboard's environment. That turns the address check off and also allowshttp://.
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.
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-Signaturestringv1=followed by the hex HMAC-SHA256 of{timestamp}.{raw body}, keyed with your signing secret.User-AgentstringVoip9-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.
signature = "v1=" + hex( HMAC_SHA256( key = signing secret, message = X-Voip9-Timestamp + "." + raw body ) )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)1import hashlib, hmac, json, os, time2from flask import Flask, request, abort3 4SECRET = os.environ["VOIP9_WEBHOOK_SECRET"].encode() # whsec_…5app = Flask(__name__)6 7@app.post("/voip9/events")8def voip9_events():9 ts = request.headers.get("X-Voip9-Timestamp", "")10 sig = request.headers.get("X-Voip9-Signature", "")11 body = request.get_data() # raw bytes, exactly as sent12 expected = "v1=" + hmac.new(SECRET, ts.encode() + b"." + body, hashlib.sha256).hexdigest()13 if not hmac.compare_digest(sig, expected):14 abort(401)15 if not ts.isdigit() or abs(time.time() - int(ts)) > 300: # replay protection16 abort(401)17 event = json.loads(body)18 queue_for_processing(event) # event["id"] is stable across retries19 return "", 2001<?php2// webhook.php3$secret = getenv('VOIP9_WEBHOOK_SECRET'); // whsec_…4$body = file_get_contents('php://input'); // raw body, before json_decode5$ts = $_SERVER['HTTP_X_VOIP9_TIMESTAMP'] ?? '';6$sig = $_SERVER['HTTP_X_VOIP9_SIGNATURE'] ?? '';7 8$expected = 'v1=' . hash_hmac('sha256', $ts . '.' . $body, $secret);9if (!hash_equals($expected, $sig) || abs(time() - (int) $ts) > 300) {10 http_response_code(401);11 exit;12}13 14$event = json_decode($body, true);15// $event['id'] is the same on every retry: skip it if you have seen it16queue_for_processing($event);17http_response_code(200);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.
| Attempt | Sent | Time since the first attempt |
|---|---|---|
| 1 | As soon as the event is queued | 0 |
| 2 | 30 s after attempt 1 fails | about 30 s |
| 3 | 1 min later | about 1.5 min |
| 4 | 2 min later | about 3.5 min |
| 5 | 4 min later | about 7.5 min |
| 6 | 8 min later | about 15.5 min |
| 7 | 16 min later | about 31.5 min |
| 8 | 32 min later, the last attempt | about 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.
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.
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.completedandcall.missed; a recorded call later sendstranscript.ready, thencall.analyzedand possiblykeyword.detected. - Join them with
call_id(call events) orrecording(transcript and analysis events).call.completedcarries both.
Testing and redelivery
- Send test event on an endpoint queues a
pingfor 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.
| Event | Sent when |
|---|---|
call.completed | Every call that ended, in any direction and with any outcome. Sent a few seconds after the last leg hangs up. |
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. |
voicemail.received | A caller left a voicemail in a person's mailbox. |
queue.abandoned | The caller hung up while waiting in a queue. |
queue.timeout | The caller waited the queue's maximum time and was sent to its fallback. Same fields as queue.abandoned. |
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. |
call.analyzed | The AI analysis of a recorded call is ready. Needs call analysis turned on for the organization. |
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. |
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.commented | Someone wrote or changed the note on a call. Same fields as call.tagged, with note instead of tags. |
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. |
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. |
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. |
ticket.created | A support ticket was created. |
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. |
ticket.resolved | A ticket's status became resolved or closed. Sent instead of ticket.updated for that save, with the same edit fields. |
ping | Sent 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.
directionstringinbound(from a carrier),outbound(to an outside number) orinternal.fromstring- The calling number or extension.
tostring- What was dialled: an extension, IVR, queue or outside number.
statusstringanswered,missed,voicemail,busy,failed, orai_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
recordingin 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.
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.
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
idinGET /api/v1/voicemail.
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.
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": "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_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(callerorcallee),startandendin seconds,text.
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,neutralornegative. urgencystringlow,mediumorhigh.flagsstring[]- Any of
complaint,fraud,emergency,cancellation,escalation,technical_issue,compliment.
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(callerorcallee) andquote, the first line it was said in (up to 200 characters).
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_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_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.
statusstringavailable,break,lunch,training,back_officeordnd.atstring- ISO 8601, UTC.
{ "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.
kindstringtext,image,audio,document,locationorother.textstring- The message text; empty for media without a caption.
received_atstring- ISO 8601, UTC.
{ "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.
statusstringopen,pending,resolvedorclosed.prioritystringlow,normal,highorurgent.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>" }.
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.
statusstringopen,pending,resolvedorclosed.prioritystringlow,normal,highorurgent.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.
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.
{ "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.
{ "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.