Skip to navigation

Webhooks

A webhook is an address of your system to which VoxAI sends a signed POST request when something that concerns you happens: a call ended, the Report card is ready, a campaign finished. This way you do not need to poll the API.

Turning webhooks on

Webhooks are a feature of the plan. They are managed in the app (Sviluppatori, then Webhook, for Owners and Admins) or through the API with the webhooks:manage scope. If the feature is not included in the plan, writes answer 403 feature_not_available.

To create an endpoint through the API:

curl -X POST https://api.getvoxai.com/v1/webhook-endpoints \
-H "Authorization: Bearer $VOXAI_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/hooks/voxai",
"events": ["call.ended", "call.analyzed"],
"description": "CRM"
}'

The 201 response contains secret, the signing secret (whsec_…). It is shown only once: store it right away. A repeated request with the same Idempotency-Key returns secret: null with Idempotent-Replay-Secret-Omitted: true. If you lose it, rotate the secret.

Rules on the address:

  • https only, on port 443;
  • at most 2048 characters, with no credentials and no fragment;
  • it must be reachable from the Internet: addresses of internal networks are refused (422 invalid_webhook_url);
  • redirects are not followed: if the address answers with a 3xx, the delivery fails. Configure the final address directly.

Rules on subscriptions:

  • each event type is chosen by name; there is no subscription to all events. A new type reaches nobody until you choose it;
  • at most 20 types per endpoint;
  • to subscribe to a type you also need the read scope of its family (table below). webhooks:manage alone opens no data;
  • an endpoint created after something happened does not receive it.

Events

GET /v1/webhook-event-types lists the available types with the scope they need.

EventWhenScope to subscribe
call.startedA call startscalls:read
call.endedA call ends (completed, interrupted or failed)calls:read
call.missedAn inbound call was not answeredcalls:read
call.analyzedThe Report card, the collected data and the summary are readycalls:read
call.transferredThe call was passed to a person who answeredcalls:read
campaign.started, campaign.paused, campaign.completedThe campaign starts or resumes, stops, finishescampaigns:read
campaign.contact.completedA contact of a campaign list has a final outcomecampaigns:read
knowledge.document.indexed, knowledge.document.failedA Knowledge base document is ready or could not be indexedknowledge:read
usage.threshold_reachedThe minutes or SMS of the period reach 80% or 100% of those includedusage:read
line.activated, line.status_changedA Line is activated or changes statelines:read
caller_request.receivedA caller’s request enters the registercaller_requests:manage
license.changedThe license is activated, renewed, changed, reactivated, expired, suspended or closedusage:read
license.expiringThe license is about to endusage:read
payment.failedThe subscription charge did not succeedusage:read
sms.sent, sms.failedAn Agent sent an SMS during a call, or the SMS did not go outcalls:read
webhook.testOnly the test (POST /v1/webhook-endpoints/{endpoint_id}/test): it cannot be subscribed tonone

Event objects have the same fields as the v1 API responses. They never contain costs, prices or details of the internal configuration. SMS events never carry the text of the message.

The envelope

Each request has a JSON body of this shape:

{
"id": "5b9f3c2e-…",
"object": "event",
"type": "call.ended",
"api_version": "2026-10-01",
"created_at": "2026-10-04T10:00:00.000Z",
"organization_id": "…",
"data": {
"object": { "object": "call", "id": "…", "status": "completed" }
}
}
  • id identifies the event and is the same at every retry.
  • data.object is the resource, with the same shape it has in the API (for example a call as in GET /v1/calls/{call_id}).
  • The transcript is left out by default. It can be included per endpoint with include_transcript, only on call.ended and call.analyzed, and it requires the calls:read scope. If the body exceeds 256 KiB, the transcript is removed and data.object contains transcript_omitted: "too_large".

Headers

Each request is a POST with Content-Type: application/json, User-Agent: VoxAI-Webhooks/1.0 and these headers:

HeaderContent
VoxAI-Event-IdThe id of the event (equal to id in the body).
VoxAI-Event-TypeThe type of event.
VoxAI-Delivery-IdThe id of the delivery.
VoxAI-Delivery-AttemptThe number of the attempt.
VoxAI-SignatureThe signature, described below.

The signature

VoxAI-Signature: t=1791021600,v1=<hex>[,v1=<hex>]
  • t is a time in Unix seconds. It is computed again at every attempt.
  • Each v1 is the HMAC-SHA256, in hexadecimal, of the string <t>.<raw body>.
  • The HMAC key is the whole secret string (whsec_…), in UTF-8.
  • While the secret is being rotated there are two v1 values (the new secret’s first): accept the request if any signature matches.

To verify, in order:

  1. Read the raw body: the bytes received, not the JSON rewritten by a parser. A single different byte changes the signature.
  2. Refuse the request if the difference between the current time and t is over 300 seconds (protection against replays).
  3. Compute the HMAC and compare it in constant time with each v1.
  4. Deduplicate on the event id.
  5. Answer with a 2xx within 10 seconds and process the event afterwards.
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
const SECRET = process.env.VOXAI_WEBHOOK_SECRET; // whsec_…
const TOLERANCE_SECONDS = 300;
function validSignature(body, header) {
const parts = header.split(",").map((p) => p.trim());
const t = parts.find((p) => p.startsWith("t="))?.slice(2);
const signatures = parts.filter((p) => p.startsWith("v1=")).map((p) => p.slice(3));
if (!t || !/^\d{1,12}$/.test(t) || signatures.length === 0) return false;
if (Math.abs(Date.now() / 1000 - Number(t)) > TOLERANCE_SECONDS) return false;
const expected = createHmac("sha256", SECRET)
.update(`${t}.`)
.update(body) // Buffer with the raw bytes
.digest("hex");
let valid = false;
for (const signature of signatures) {
if (
signature.length === expected.length &&
timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
) {
valid = true;
}
}
return valid;
}
const app = express();
// The body must stay raw: no express.json() on this route.
app.post("/hooks/voxai", express.raw({ type: "application/json" }), (req, res) => {
if (!validSignature(req.body, req.get("VoxAI-Signature") ?? "")) {
return res.sendStatus(400);
}
const event = JSON.parse(req.body.toString("utf8"));
// Deduplicate on event.id, then queue the processing.
res.sendStatus(200);
});
app.listen(3000);

Delivery and retries

Delivery is at least once: the same event can arrive more than once, and the order of arrival is not guaranteed. Use created_at to order and, if needed, read the resource again through the API.

  • A 2xx response counts as delivered. Anything else, 3xx included, is a failure.
  • The timeout is 10 seconds. At most 1 KiB of your response body is kept.
  • Events usually go out within about twenty seconds of what happened.

There are 8 attempts over about 24 hours from when the delivery is created, each with a random variation of about 10%:

AttemptWhen
1At once
2After 1 minute
3After 5 minutes
4After 30 minutes
5After 2 hours
6After 6 hours
7After 12 hours
8After 24 hours

After the eighth attempt the delivery is failed. A delivery left in the queue for over 72 hours (for example because the endpoint is paused) is closed as failed.

Automatic disabling

An endpoint goes to status: "disabled" (with disabled_reason: "repeated_failures") when it has at least 10 failed deliveries in a row and no success in the last 3 days. Owners get an email. To turn it on again, fix the problem and use the app or PATCH /v1/webhook-endpoints/{endpoint_id} with status: "active": its failure counters restart from zero.

An endpoint disabled by VoxAI staff (disabled_reason: "platform") cannot be reactivated through the API: PATCH answers 403 webhook_endpoint_disabled_by_platform. Contact support.

To suspend deliveries yourself use status: "paused".

Idempotency on the receiving side

Since delivery is at least once, your receiver must tolerate duplicates:

  1. Store the id of each event already processed (even just for a few days).
  2. If an id you have already seen arrives, answer 2xx without processing it again.
  3. Answer quickly and move heavy work to a queue: over 10 seconds the delivery fails and will be retried.
  4. Do not rely on the order: compare created_at or read the resource again.

Testing and resending

  • POST /v1/webhook-endpoints/{endpoint_id}/test sends a webhook.test event at once, with a single attempt, and returns the outcome.
  • POST /v1/webhook-deliveries/{delivery_id}/resend sends a delivery again with the same body, as long as the body is kept (7 days after the outcome, then 409 webhook_delivery_expired).
  • GET /v1/webhook-endpoints/{endpoint_id}/deliveries lists the deliveries and their outcome, without the body.

Tests and resends have an hourly limit; over it the response is 429 rate_limited with Retry-After.

With a test key, creation, changes, rotation, test and resend are simulated: nothing is sent and no secret is generated.

Rotating the secret

POST /v1/webhook-endpoints/{endpoint_id}/rotate-secret creates a new secret (201 response, shown only once). The overlap_hours parameter (0 to 72, 24 by default) says how long the old secret stays valid: during that time every request carries two v1 signatures. Update the secret in your receiver, then let the old one expire.