> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getvoxai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getvoxai.com/_mcp/server.

# 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:

```bash
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.

| Event                                                       | When                                                                                        | Scope to subscribe       |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------ |
| `call.started`                                              | A call starts                                                                               | `calls:read`             |
| `call.ended`                                                | A call ends (completed, interrupted or failed)                                              | `calls:read`             |
| `call.missed`                                               | An inbound call was not answered                                                            | `calls:read`             |
| `call.analyzed`                                             | The Report card, the collected data and the summary are ready                               | `calls:read`             |
| `call.transferred`                                          | The call was passed to a person who answered                                                | `calls:read`             |
| `campaign.started`, `campaign.paused`, `campaign.completed` | The campaign starts or resumes, stops, finishes                                             | `campaigns:read`         |
| `campaign.contact.completed`                                | A contact of a campaign list has a final outcome                                            | `campaigns:read`         |
| `knowledge.document.indexed`, `knowledge.document.failed`   | A Knowledge base document is ready or could not be indexed                                  | `knowledge:read`         |
| `usage.threshold_reached`                                   | The minutes or SMS of the period reach 80% or 100% of those included                        | `usage:read`             |
| `line.activated`, `line.status_changed`                     | A Line is activated or changes state                                                        | `lines:read`             |
| `caller_request.received`                                   | A caller's request enters the register                                                      | `caller_requests:manage` |
| `license.changed`                                           | The license is activated, renewed, changed, reactivated, expired, suspended or closed       | `usage:read`             |
| `license.expiring`                                          | The license is about to end                                                                 | `usage:read`             |
| `payment.failed`                                            | The subscription charge did not succeed                                                     | `usage:read`             |
| `sms.sent`, `sms.failed`                                    | An Agent sent an SMS during a call, or the SMS did not go out                               | `calls:read`             |
| `webhook.test`                                              | Only the test (`POST /v1/webhook-endpoints/{endpoint_id}/test`): it cannot be subscribed to | none                     |

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:

```json
{
  "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:

| Header                   | Content                                          |
| ------------------------ | ------------------------------------------------ |
| `VoxAI-Event-Id`         | The id of the event (equal to `id` in the body). |
| `VoxAI-Event-Type`       | The type of event.                               |
| `VoxAI-Delivery-Id`      | The id of the delivery.                          |
| `VoxAI-Delivery-Attempt` | The number of the attempt.                       |
| `VoxAI-Signature`        | The 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.

#### Node.js (Express)

```js
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);
```

#### Python (Flask)

```python
import hashlib
import hmac
import os
import re
import time

from flask import Flask, request

SECRET = os.environ["VOXAI_WEBHOOK_SECRET"]  # whsec_…
TOLERANCE_SECONDS = 300

app = Flask(__name__)


def valid_signature(body: bytes, header: str) -> bool:
    parts = [p.strip() for p in header.split(",")]
    t = next((p[2:] for p in parts if p.startswith("t=")), None)
    signatures = [p[3:] for p in parts if p.startswith("v1=")]
    if t is None or not re.fullmatch(r"\d{1,12}", t) or not signatures:
        return False
    if abs(time.time() - int(t)) > TOLERANCE_SECONDS:
        return False

    expected = hmac.new(
        SECRET.encode("utf-8"),
        t.encode() + b"." + body,
        hashlib.sha256,
    ).hexdigest()

    valid = False
    for signature in signatures:
        if hmac.compare_digest(signature, expected):
            valid = True
    return valid


@app.post("/hooks/voxai")
def voxai():
    body = request.get_data()  # the raw bytes, before any parsing
    if not valid_signature(body, request.headers.get("VoxAI-Signature", "")):
        return "", 400
    event = request.get_json(force=True)
    # Deduplicate on event["id"], then queue the processing.
    return "", 200
```

## 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%:

| Attempt | When             |
| ------- | ---------------- |
| 1       | At once          |
| 2       | After 1 minute   |
| 3       | After 5 minutes  |
| 4       | After 30 minutes |
| 5       | After 2 hours    |
| 6       | After 6 hours    |
| 7       | After 12 hours   |
| 8       | After 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.