Get notified

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

  1. Choose Add webhook.
  2. Enter the Destination address, an https URL, for example https://your-server.example.com/webhooks/verticalai.
  3. Optionally add a description so the row is recognisable later.
  4. 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…
  • t is the time the request was sent, in Unix seconds.
  • v1 is the HMAC-SHA256 of t, a full stop, then the raw request body, keyed with your signing secret, hex encoded.

To verify a request:

  1. Read t and v1 from the header.
  2. Compute the HMAC-SHA256 of <t>.<raw body> with your signing secret.
  3. Compare it with v1 in constant time.
  4. Reject the request when t is 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:

StatusMeaning
DeliveredAn attempt got a 2xx answer
RetryingAttempts have failed and the next one is scheduled
FailedAll 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": "…"}.

On this page