Skip to content
AvraAvra
Esc
↑↓navigate↵open⌘Jpreview
On this page

Webhooks

HTTPS callbacks for batch, model version, workspace, and API key events, configured for your organization.

Webhooks send event notifications to your endpoints over HTTPS, so your systems don’t have to poll the API.

The workflow takes five steps. Add an endpoint in the dashboard and subscribe it to the events you need. On each delivery, verify the signature with the endpoint’s signing secret, answer 2xx at once, and hand the event to a worker. The worker deduplicates it, then reads the resource it’s about from the API, because a delivery says what happened, not the resource’s current state.

Configure endpoints

Webhook endpoints are managed in the dashboard under Alerts → Webhooks, by members with permission to manage webhooks. They apply to your whole organization. See Roles & permissions.

For each endpoint, you set the destination URL that receives deliveries and subscribe to the events you need. You use its signing secret to verify deliveries, and you can rotate the secret. Its delivery history shows payloads, response codes, and retries, and lets you replay deliveries manually.

You can register several endpoints, for example to route operational events to one consumer and audit events to another. Use a separate endpoint for each environment, so each has its own secret and delivery history.

Event catalog

Batches

Event Sent when
batch-request A batch prediction was requested
batch-running A batch started running
batch-ended A batch finished: completed, failed, or cancelled
batch-result-download A batch result was downloaded

batch-running and batch-ended follow the batch’s status. No event is sent for pending, queued, concluding, or cancelling, and batch-ended doesn’t say which of the three endings it was, so read the batch to find out.

The deprecated v1 batch flow also sends batch-input-upload-request, batch-input-deletion, batch-interrupt-request, and batch-result-deletion.

Model versions

Event Sent when
model-version-activation A model version was activated
model-version-deactivation A model version was deactivated
model-version-promotion A model version was promoted: an alias was assigned to it
model-version-demotion A model version was demoted: its alias was removed

Reassigning an alias sends one model-version-promotion, for the version that receives it. See Model versioning.

Workspaces

Event Sent when
workspace-creation A workspace was created
workspace-update A workspace’s settings were updated
workspace-archival A workspace was archived
workspace-unarchival A workspace was unarchived

API keys

Event Sent when
api-key-creation An API key was created
api-key-recycling An API key was rotated
api-key-renaming An API key was renamed
api-key-deletion An API key was deleted

Payloads

Every delivery is an HTTPS POST with a JSON body. The body identifies what happened, but not the resource’s state:

{
  "idempotency_key": "evt-5f0c9a7e-2b1d-4e8a-9c3f-71d2e6b8a404",
  "event": "batch-ended",
  "event_at": "2026-11-09T14:31:07.482913Z"
}
Field Type Description
idempotency_key string The same for every delivery of one event. Deduplicate on it, and treat it as opaque
event string The event’s name, from the event catalog
event_at string When it happened, as an RFC 3339 timestamp
resource_type string The kind of resource the event is about. Omitted when empty
resource_id string That resource’s ID. Omitted when empty

Don’t depend on resource_type and resource_id being present. Fetch the resource for its details instead: after batch-ended, for example, call GET /v2/api/batches/{id} for the batches you’re waiting on to read their final status. Read the current state before you act on any event: workspace, API key, and model version events can also record an attempt that didn’t succeed.

Each delivery carries three headers for verification:

Header Contents
svix-id The message’s unique ID
svix-timestamp When the delivery was sent, in seconds since the Unix epoch
svix-signature One or more signatures separated by spaces, each written as v1, followed by a base64-encoded signature

Verify deliveries

Every delivery is signed with HMAC SHA-256 using the endpoint’s signing secret. Verify every delivery before you trust it:

Decode the secret

The signing secret starts with whsec_. Base64-decode the part after that prefix: those bytes are the key.

Rebuild the signed content

Join the svix-id header, the svix-timestamp header, and the raw request body with periods: {svix-id}.{svix-timestamp}.{body}. Use the body exactly as it arrived, before any JSON parsing.

Compute and compare

Compute the HMAC SHA-256 of the signed content with the key, and base64-encode it. Compare it with each v1 signature in the svix-signature header using a constant-time comparison, and accept the delivery if any matches.

Check the timestamp

Reject deliveries whose timestamp is outside your tolerance window; 5 minutes is a sensible default.

These receivers verify deliveries, answer at once, and deduplicate on idempotency_key. Set AVRA_WEBHOOK_SECRET to the endpoint’s signing secret.

# A receiver built with Flask.
import base64
import hashlib
import hmac
import os
import time

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = base64.b64decode(os.environ["AVRA_WEBHOOK_SECRET"].removeprefix("whsec_"))
TOLERANCE_SECONDS = 5 * 60
seen: set[str] = set()  # handled idempotency keys; keep them in your database in production


def verify(msg_id: str, timestamp: str, signatures: str, body: bytes) -> bool:
    try:
        if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
            return False
    except ValueError:
        return False
    signed = f"{msg_id}.{timestamp}.".encode() + body
    expected = base64.b64encode(hmac.new(SECRET, signed, hashlib.sha256).digest())
    for entry in signatures.split(" "):
        version, _, signature = entry.partition(",")
        if version == "v1" and hmac.compare_digest(signature.encode(), expected):
            return True
    return False


@app.post("/webhooks/avra")
def receive():
    body = request.get_data()  # the raw bytes, exactly as sent
    if not verify(
        request.headers.get("svix-id", ""),
        request.headers.get("svix-timestamp", ""),
        request.headers.get("svix-signature", ""),
        body,
    ):
        abort(401)
    event = request.get_json()
    if event["idempotency_key"] not in seen:
        seen.add(event["idempotency_key"])
        print("received", event["event"], event["event_at"])  # hand off to your queue here
    return "", 204
// A receiver built on Node's http module, with no dependencies.
import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";

const secret = Buffer.from(process.env.AVRA_WEBHOOK_SECRET!.replace(/^whsec_/, ""), "base64");
const TOLERANCE_SECONDS = 5 * 60;
const seen = new Set<string>(); // handled idempotency keys; keep them in your database in production

function verify(id: string, timestamp: string, signatures: string, body: Buffer): boolean {
  const sentAt = Number(timestamp);
  if (!Number.isInteger(sentAt) || Math.abs(Date.now() / 1000 - sentAt) > TOLERANCE_SECONDS) {
    return false;
  }
  const expected = Buffer.from(
    createHmac("sha256", secret).update(`${id}.${timestamp}.`).update(body).digest("base64"),
  );
  return signatures.split(" ").some((entry) => {
    const [version, signature] = entry.split(",");
    if (version !== "v1" || !signature) return false;
    const received = Buffer.from(signature);
    return received.length === expected.length && timingSafeEqual(received, expected);
  });
}

createServer((req, res) => {
  const chunks: Buffer[] = [];
  req.on("data", (chunk: Buffer) => chunks.push(chunk));
  req.on("end", () => {
    const body = Buffer.concat(chunks); // the raw bytes, exactly as sent
    const header = (name: string) => String(req.headers[name] ?? "");
    const valid =
      req.method === "POST" &&
      verify(header("svix-id"), header("svix-timestamp"), header("svix-signature"), body);
    if (!valid) {
      res.writeHead(401).end();
      return;
    }
    const event = JSON.parse(body.toString("utf8"));
    if (!seen.has(event.idempotency_key)) {
      seen.add(event.idempotency_key);
      console.log("received", event.event, event.event_at); // hand off to your queue here
    }
    res.writeHead(204).end();
  });
}).listen(3000);

Verify against the raw body. A framework that parses the JSON and serializes it again can change the bytes, such as the spacing or the key order, and the signature no longer matches.

Retries

Deliveries are at least once. A delivery that fails, with a non-2xx response or a timeout, is retried with exponential backoff. Once the retries run out, it’s marked failed in the delivery history, where you can inspect and replay it.

Because a delivery can arrive more than once, and a replay sends it again, process each idempotency_key once. Because a slow answer counts as a failure, acknowledge first and do the work afterward.

Practices that help

Respond quickly: acknowledge the delivery at once and process it asynchronously. Deduplicate on the idempotency key, since a delivery can arrive more than once. Use a separate endpoint for each environment, so each has its own secret and delivery history. Subscribe only to the events you consume. When you rotate an endpoint’s signing secret, update it in your receiver too.

Where to go next

Was this page helpful?