Webhooks
Receive signed HTTP events for calls, leads, campaigns, alerts and analysis on your own endpoint.
A webhook is an HTTPS endpoint that the platform posts to when something
happens in your workspace. Every event is a POST with
Content-Type: application/json:
{
"id": "…",
"event": "conversation.ended",
"data": {
"sessionId": "…",
"agentId": "…"
}
}id is the event's id, also sent in the X-VAI-Event-Id header. event is
the event name. data carries the payload. The fourteen events are catalogued on
Webhook events and
Campaign webhook events.
Webhooks are configured per workspace. They come with the Growth plan and up. On a plan without them, such as Starter, a webhook can't be created or switched on, and no events are sent.
Where webhooks are configured
Settings > Webhooks, in the Developers group. Only a workspace owner or admin sees it, and only they can create, edit, test, delete a webhook or rotate its secret.
The same jobs are in the REST API under
/api/v1/workspaces/{workspace}/webhooks, and in the MCP server as
create_workspace_webhook, update_workspace_webhook and the rest. A token
needs Manage the workspace access to create, change, test or delete a
webhook, rotate its secret or redeliver an event.
Create a webhook
- Choose Add webhook.
- Enter the Destination address, an
httpsURL, for examplehttps://your-server.example.com/webhooks/verticalai. - Optionally add a description so the row is recognisable later.
- Choose Create webhook.
New webhooks start subscribed to every event.
The signing secret
A signing secret is generated for you at creation. Expand the row to read it, and use Rotate to replace it.
The old secret stops working at once. Every delivery after the rotation, retries included, is signed with the new one, so give your receiver the new secret straight away.
Verify the signature
Every request carries an X-VAI-Signature header:
X-VAI-Signature: t=1791169200,v1=6f1d0c2b…tis the time the request was sent, in Unix seconds.v1is the HMAC-SHA256 oft, a full stop, then the raw request body, keyed with your signing secret, hex encoded.
To verify a request:
- Read
tandv1from the header. - Compute the HMAC-SHA256 of
<t>.<raw body>with your signing secret. - Compare it with
v1in constant time. - Reject the request when
tis more than five minutes from your own clock.
The timestamp is inside the signature, so a captured request cannot be replayed
once those five minutes pass. Each delivery attempt is signed when it is sent,
so a retried event carries a fresh t.
Verify before you parse: re-serialising the JSON changes the bytes and breaks the match.
import { createHmac, timingSafeEqual } from "node:crypto";
const TOLERANCE_SECONDS = 5 * 60;
/** rawBody: the exact bytes received, before any JSON parsing. */
function signatureIsValid(rawBody, header, secret) {
const parts = Object.fromEntries(
(header ?? "").split(",").map((part) => part.split("=", 2)),
);
const t = Number(parts.t);
if (!Number.isInteger(t) || !parts.v1) return false;
if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) return false;
const expected = createHmac("sha256", secret)
.update(`${t}.`)
.update(rawBody)
.digest("hex");
const a = Buffer.from(expected, "utf8");
const b = Buffer.from(parts.v1, "utf8");
return a.length === b.length && timingSafeEqual(a, b);
}
// Express, with the raw body preserved:
app.post(
"/webhooks/verticalai",
express.raw({ type: "application/json" }),
(req, res) => {
if (!signatureIsValid(req.body, req.get("X-VAI-Signature"), SECRET)) {
return res.status(401).end();
}
const { event, data } = JSON.parse(req.body.toString("utf8"));
// …handle the event, then answer quickly.
res.status(200).end();
},
);The same check in Python:
import hashlib
import hmac
import time
TOLERANCE_SECONDS = 5 * 60
def signature_is_valid(raw_body: bytes, header: str | None, secret: str) -> bool:
parts = dict(part.split("=", 1) for part in (header or "").split(",") if "=" in part)
try:
t = int(parts["t"])
except (KeyError, ValueError):
return False
if abs(time.time() - t) > TOLERANCE_SECONDS or "v1" not in parts:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])Reject any request whose signature does not match or whose timestamp is too old. Treat a missing header as unsigned, not trusted.
Delivery
Each event is posted to every active, subscribed webhook in the workspace. Setting a webhook inactive stops delivery without deleting the row or the secret.
Redirects are not followed
Give the endpoint's final URL. A 3xx answer counts as a failed delivery, and
the platform does not follow it.
The endpoint must resolve to a public address. A host that resolves to a private, loopback or link-local address is refused on every delivery, not only when the webhook is created. The Test button follows the same rules.
Failed deliveries are retried
A broken endpoint cannot abort a call teardown or the rest of the fan-out. A delivery that does not get a 2xx answer is retried, up to eight attempts in all. The wait between attempts doubles from 30 seconds to at most 15 minutes, so the last attempt comes about 45 minutes after the first, and after that the event is dropped.
When an event is dropped, the workspace's notification recipients get an email
naming the webhook, the events and event ids it dropped in the last hour, the
last error, and the time to reconcile from. It is sent at most once an hour for
each webhook while its deliveries keep failing. Switch it off with the
Webhook delivery failed notification, or webhookDeliveryFailed in
set_workspace_notifications. Every attempt for one event carries the same
X-VAI-Event-Id header, so use it to ignore an event you have already handled.
Reconcile against the call list if you
need a guaranteed record of calls. For leads, the get_lead_callback tool on
the MCP server lists an agent's lead requests for a date range (since,
until, up to 200), each with the id its lead events carry as
leadRequestId. Lead requests are kept for 30 days.
Answer quickly
Acknowledge with a 2xx and do your work afterwards. Each attempt waits ten seconds for an answer. A slower answer counts as a failed attempt and is retried, so a slow receiver gets the same event again.
The delivery log
Every event sent to a webhook is recorded with each attempt to deliver it. Expand a webhook in Settings > Webhooks and its Recent deliveries list the newest events first, each with its status:
| Status | Meaning |
|---|---|
| Delivered | An attempt got a 2xx answer |
| Retrying | Attempts have failed and the next one is scheduled |
| Failed | All eight attempts failed, or the webhook was switched off or unsubscribed before the event went out |
Open a delivery to see each attempt: its number, when it was sent, the HTTP status, how long your server took to answer, and the first 300 characters of its reply, or the error when it did not answer.
The same log is in the REST API at
GET /api/v1/workspaces/{workspace}/webhooks/{webhook}/deliveries (filter
with status and event, page with limit and cursor), and in the MCP
server as list_webhook_deliveries.
Redeliver an event
After you fix your receiver, send a missed event again with Redeliver in
the delivery log, POST /api/v1/workspaces/{workspace}/webhooks/{webhook}/deliveries/{event}/redeliver,
or redeliver_webhook_event. It is signed afresh and carries the same body and
the same X-VAI-Event-Id, so a receiver that ignores ids it has handled stays
correct. The webhook must be switched on. The new attempts are marked as
redeliveries in the log, and a failed redelivery is retried like any other
delivery.
An event's body is kept for seven days so it can be sent again, or for as long as the agent or workspace keeps call data when that is shorter. A workspace that keeps no call data keeps no bodies, so its events cannot be redelivered. The record of the delivery and its attempts stays after the body is cleared.
Reading the log and redelivering need the owner or admin role.
Test an endpoint
Each event row in an expanded webhook has a Test button that posts a sample body and reports the HTTP status and round-trip time (ten-second timeout).
The test uses the real envelope and the real X-VAI-Signature and
X-VAI-Event-Id headers, so the same receiver code handles it. Its id
starts with test_ and its data is a placeholder:
{"test": true, "workspaceId": "…", "timestamp": "…"}.