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.