---
title: Webhooks
description: 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.

```mermaid
sequenceDiagram
  autonumber
  participant A as Avra
  participant E as Your endpoint
  participant W as Your worker
  A->>E: POST signed event
  E->>E: Verify signature
  E->>W: Enqueue
  E-->>A: 2xx at once
  W->>W: Skip seen idempotency_key
  W->>A: GET the resource
  opt No 2xx, or a timeout
    loop Exponential backoff
      A->>E: Same delivery again
    end
    Note over A: Marked failed,<br/>ready to replay
  end
```

## 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](/dashboard/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](/core/batch-inference#batch-statuses). 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](/core/model-versioning#events).

### 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:

```json
{
  "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-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:

1. **Decode the secret**

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

2. **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.

3. **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.

4. **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.

```python Python
# 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
```

```ts TypeScript
// 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

**[Batch inference](/core/batch-inference#use-webhooks-instead-of-polling)**

Run batches without polling.

**[Model versioning](/core/model-versioning)**

What sends the `model-version-*` events.

**[Notifications](/dashboard/notifications)**

Alerts for the people on your team.

**[Limits and quotas](/core/limits)**

Delivery and signature limits, with the rest of Core.
