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

# Webhooks

> Get push notifications when campaigns hit lifecycle events. No polling required.

Webhooks let you react to events in Ontora — a campaign starting, an interview completing, synthesis finishing — without polling.

## How they work

1. You register an HTTPS endpoint and the events you want.
2. Ontora signs and POSTs JSON to your endpoint when a matching event occurs.
3. Your endpoint verifies the signature and processes the payload.
4. If your endpoint returns non-2xx, Ontora retries with exponential backoff.

## Register an endpoint

Requires an API key with the `webhooks` scope.

```bash theme={null}
curl -X POST https://api.ontora.com/v1/webhook-endpoints \
  -H "X-API-Key: $ONTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "ws_...",
    "url": "https://example.com/webhooks/ontora",
    "events": ["synthesis.completed", "interview.completed"],
    "description": "Production sync"
  }'
```

```json theme={null}
{
  "id": "we_...",
  "secret": "whsec_...",
  "url": "https://example.com/webhooks/ontora",
  "events": ["synthesis.completed", "interview.completed"],
  "active": true,
  "created_at": "2026-04-24T18:30:00Z"
}
```

<Warning>
  The `secret` is **only returned on creation**. Save it now — you'll use it to verify every incoming request. See [Signing & verification](/webhooks/signing).
</Warning>

To subscribe to **all** events, pass `"events": []`.

## Test an endpoint

Triggers a real delivery with a synthetic payload — useful for confirming your handler is wired up:

```bash theme={null}
curl -X POST https://api.ontora.com/v1/webhook-endpoints/we_.../test \
  -H "X-API-Key: $ONTORA_API_KEY"
```

## Inspect deliveries

Every delivery is logged with the response status, attempt count, and last error if any:

```bash theme={null}
curl https://api.ontora.com/v1/webhook-endpoints/we_.../deliveries?limit=20 \
  -H "X-API-Key: $ONTORA_API_KEY"
```

```json theme={null}
[
  {
    "id": "wd_...",
    "status": "delivered",
    "attempts": 1,
    "response_status": 200,
    "last_error": null,
    "delivered_at": "2026-04-24T18:31:02Z"
  }
]
```

## Retries

Failed deliveries (non-2xx response, timeout, network error) retry up to 3 times with exponential backoff. After max attempts the delivery is marked `failed` and stays that way — Ontora will not retry it later. Use the deliveries list to find and replay failures from your side.

Per-attempt timeout: **10 seconds**.

## Disable an endpoint

Toggle `active: false` to stop deliveries without deleting the subscription:

```bash theme={null}
curl -X PATCH https://api.ontora.com/v1/webhook-endpoints/we_... \
  -H "X-API-Key: $ONTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active": false}'
```

Inactive endpoints are skipped at emission time — no deliveries are queued, so there's nothing to replay.

## Next steps

<CardGroup cols={2}>
  <Card title="Event types" icon="list" href="/webhooks/events">
    Every event Ontora can send, with payload shapes.
  </Card>

  <Card title="Signing & verification" icon="lock" href="/webhooks/signing">
    HMAC-SHA256 signature verification — code samples included.
  </Card>
</CardGroup>