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:
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:
httpsonly, 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:managealone 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 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:
ididentifies the event and is the same at every retry.data.objectis the resource, with the same shape it has in the API (for example a call as inGET /v1/calls/{call_id}).- The transcript is left out by default. It can be included per endpoint with
include_transcript, only oncall.endedandcall.analyzed, and it requires thecalls:readscope. If the body exceeds 256 KiB, the transcript is removed anddata.objectcontainstranscript_omitted: "too_large".
Headers
Each request is a POST with Content-Type: application/json, User-Agent: VoxAI-Webhooks/1.0 and these headers:
The signature
tis a time in Unix seconds. It is computed again at every attempt.- Each
v1is 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
v1values (the new secret’s first): accept the request if any signature matches.
To verify, in order:
- Read the raw body: the bytes received, not the JSON rewritten by a parser. A single different byte changes the signature.
- Refuse the request if the difference between the current time and
tis over 300 seconds (protection against replays). - Compute the HMAC and compare it in constant time with each
v1. - Deduplicate on the event
id. - Answer with a
2xxwithin 10 seconds and process the event afterwards.
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
2xxresponse counts as delivered. Anything else,3xxincluded, 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%:
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:
- Store the
idof each event already processed (even just for a few days). - If an
idyou have already seen arrives, answer2xxwithout processing it again. - Answer quickly and move heavy work to a queue: over 10 seconds the delivery fails and will be retried.
- Do not rely on the order: compare
created_ator read the resource again.
Testing and resending
POST /v1/webhook-endpoints/{endpoint_id}/testsends awebhook.testevent at once, with a single attempt, and returns the outcome.POST /v1/webhook-deliveries/{delivery_id}/resendsends a delivery again with the same body, as long as the body is kept (7 days after the outcome, then409 webhook_delivery_expired).GET /v1/webhook-endpoints/{endpoint_id}/deliverieslists 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.