> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Real-time HTTPS callbacks for batch, model, workspace, and API-key events — configured per workspace.

Webhooks deliver real-time event notifications to your endpoints over HTTPS, eliminating the need to poll the API for job status or operational changes.

## Configure endpoints

Webhook endpoints are managed in the dashboard under **Platform → Alerts → Webhooks**.

For each endpoint you can:

* Set the **destination URL** that will receive deliveries
* **Subscribe** to specific events (you do not need to handle every event)
* Use the **signing secret** to verify deliveries with HMAC SHA-256
* View the **delivery history** to inspect payloads, response codes, and retry status

You can register multiple endpoints per workspace — useful for routing operational events to one consumer and audit events to another.

## Event catalog

All events are grouped by resource. The catalog is also available programmatically — events are added over time without breaking existing subscriptions.

### Batches

| Event                        | Description                                                                                |
| ---------------------------- | ------------------------------------------------------------------------------------------ |
| `batch-input-upload-request` | A batch input file upload was requested                                                    |
| `batch-input-deletion`       | A batch input was deleted                                                                  |
| `batch-request`              | A batch inference run was requested                                                        |
| `batch-interrupt-request`    | A batch inference interruption was requested                                               |
| `batch-lifecycle`            | A lifecycle transition occurred for a batch inference (queued, running, succeeded, failed) |
| `batch-result-download`      | A batch result was downloaded                                                              |
| `batch-result-deletion`      | A batch result was deleted                                                                 |

To act on batch completion, subscribe to `batch-lifecycle` and read the status field from the payload.

### Model versions

| Event                        | Description                                                         |
| ---------------------------- | ------------------------------------------------------------------- |
| `model-version-activation`   | A model version was activated                                       |
| `model-version-deactivation` | A model version was deactivated                                     |
| `model-version-promotion`    | A model version was promoted (e.g. assigned the `production` alias) |
| `model-version-demotion`     | A model version was demoted                                         |

### Workspace

| Event                  | Description                         |
| ---------------------- | ----------------------------------- |
| `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               | Description            |
| ------------------- | ---------------------- |
| `api-key-creation`  | An API key was created |
| `api-key-deletion`  | An API key was deleted |
| `api-key-recycling` | An API key was rotated |
| `api-key-renaming`  | An API key was renamed |

## Verifying deliveries

Every delivery is signed with HMAC SHA-256 using the endpoint's signing secret. The dashboard surfaces the secret on the endpoint detail view and lets you rotate it at any time.

To verify a delivery on your side:

1. Read the signature headers from the incoming request.
2. Recompute the HMAC SHA-256 of the payload using your endpoint's signing secret.
3. Compare against the value in the signature header using **constant-time** comparison.
4. Reject deliveries whose timestamp is outside your tolerance window (5 minutes is a sensible default).

The exact header names are documented on the endpoint detail view in the dashboard, along with a copy-pasteable verification snippet.

## Retry and delivery semantics

Avra delivers webhooks with **at-least-once** semantics. Your endpoint should treat deliveries as idempotent and dedupe on the delivery ID surfaced in the request headers.

Failed deliveries (non-2xx response or timeout) are automatically retried with exponential backoff. If all retries are exhausted, the delivery is marked failed in the dashboard and can be inspected or manually replayed from the delivery history.

## Observability

The dashboard exposes a delivery log per endpoint with response codes, payloads, and failure reasons. Useful for debugging integration issues without instrumenting your own consumer. Individual deliveries can be replayed manually.

## Best practices

* **Respond within 5 seconds.** Acknowledge the delivery immediately and process the payload asynchronously on your side.
* **Dedupe on the delivery ID.** Avra may retry deliveries; idempotent consumers prevent double-processing.
* **Use separate endpoints per environment.** Different secrets, different delivery logs, no cross-contamination.
* **Subscribe narrowly.** Register endpoints only for the events you actually consume.