1. What arrives
A single HTTP POST with a JSON body, sent as soon as the call ends or the Genie job finishes.
Content type is application/json. Every message has the same envelope:
{
"event": "ivr.completed",
"delivery_id": "8f3c2b10-...", // unique — use it to skip duplicates
"sent_at": "2026-10-31T14:22:10.512Z",
"data": { ... } // see below, depends on the event
}
2. From an IVR — ivr.completed
The keys the caller pressed, each with the label of the menu that asked and what that key meant.
"data": {
"call_uuid": "74e865a6-c304-4ad6-9843-3b6bc9b43713",
"ivr": { "name": "Confirmations Tomorrow", "extension": "80101" },
"caller_number": "+17865550142",
"destination_number": "80103",
"start_time": "2026-10-31T14:21:23.000Z",
"duration_seconds": 47,
"disconnect_reason": "IVR_COMPLETED",
"completed": true,
"answers": [
{ "label": "Main menu", "key": "1", "option": "Confirm appointment" },
{ "label": "Confirm appointment", "key": null, "option": null }
]
}
key is null when the caller did not press anything at that point, and
option is null when that branch has no label set in the IVR editor.
completed is false when they hung up before finishing the menu.
3. From an AI Agent — call.completed
"data": {
"call_uuid": "2b1f2633-7830-406e-8b6d-06256152f4c8",
"agent": { "name": "Appointment Confirmation", "extension": "80001" },
"caller_number": "+17865550142",
"destination_number": "80001",
"start_time": "2026-10-31T14:21:23.000Z",
"end_time": "2026-10-31T14:23:05.000Z",
"duration_seconds": 102,
"disconnect_reason": "AI_ENDED",
"transcript": "Agent: Hello...\nCaller: Yes, I confirm...",
"summary": "The patient confirmed the appointment for tomorrow at 9am."
}
4. From a Genie Agent — genie_run.completed / genie_run.failed
Sent when a job you started through the API (or with Test in the panel) finishes.
completed means the agent did the work; failed means it could not.
The data is the same object that GET /api/v1/genie-runs/{run_id} returns, plus failure_type.
"data": {
"run_id": "cc4b940a-61e2-4f0b-9d3a-6a1c5e2f8b71",
"agent": { "id": "5d2e...", "slug": "ecw-confirm-encounter", "name": "eCW — Confirm encounter" },
"status": "SUCCEEDED", // or "FAILED" / "CANCELLED"
"external_ref": "APPT-48213", // your own id, sent back as you gave it
"dry_run": false, // true: rehearsal, nothing was saved
"result": { // shape = the agent's output schema
"already_confirmed": false,
"encounter": { "date": "11/03/2026", "time": "09:00 AM", "previous_status": "PEN" }
},
"message": "Confirmed.",
"error": null, // why it failed, when it failed
"failure_type": null, // "agent" or "system" when it failed
"created_at": "2026-11-03T13:58:40.120Z",
"started_at": "2026-11-03T13:58:41.002Z",
"finished_at": "2026-11-03T13:59:12.874Z"
}
failure_type: "agent" — the agent decided it could not do it (record not found, several matches). Retrying will not help; check the data you sent.
failure_type: "system" — a technical problem (portal down, login, timeout). Safe to start a new job later.
- Match the result to your record with
external_ref, and skip duplicates with run_id.
- If your system updates that record when the result arrives, make sure the update does not start the same job again (for example, a CRM workflow that fires on every change). Otherwise each result triggers a new job.
- The Genie events are added to the endpoint automatically when you pick it in the Genie Agent.
5. Headers
Content-Type: application/json
User-Agent: VoizGenie-Webhook/1.0
X-VoizGenie-Event: ivr.completed
X-VoizGenie-Delivery: 8f3c2b10-...
X-VoizGenie-Signature: t=1793419094,v1=9a7f... (see below)
Plus whatever authentication you configured for the endpoint (your header, Bearer or Basic).
6. What you must answer
Any 2xx status means received; the body is ignored. Anything else — or no answer within
15 seconds — counts as a failure and we retry automatically after
1 minute, 5 minutes, 30 minutes and 2 hours, five attempts in total.
Answer quickly and do your processing afterwards: a slow endpoint turns into a retry.
Because of retries the same result can arrive twice, so treat delivery_id (or call_uuid / run_id)
as the key and ignore what you have already stored.
7. Verifying the signature (optional)
Every delivery is signed with the secret shown when the endpoint was created. It proves the request
came from us and was not altered. If your tool cannot compute an HMAC, skip this — the token in your
URL or header is already protecting the endpoint.
// Node.js
const [t, v1] = header.split(',').map(p => p.split('=')[1]);
const expected = crypto.createHmac('sha256', SECRET)
.update(`${t}.${rawBody}`) // the raw body, before parsing
.digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
&& (Date.now()/1000 - Number(t)) < 300; // reject old replays
# Python
t, v1 = [p.split('=')[1] for p in header.split(',')]
expected = hmac.new(SECRET.encode(), f"{t}.{raw_body}".encode(), hashlib.sha256).hexdigest()
ok = hmac.compare_digest(v1, expected) and (time.time() - int(t)) < 300