Webhooks

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

How they work

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

Register an endpoint

Requires an API key with the write capability (legacy webhooks keys keep working).

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": "8f4a2c10-5d3b-4e6f-9a71-2b8c0d5e7f31",
    "url": "https://example.com/webhooks/ontora",
    "events": ["synthesis.completed", "interview.completed"],
    "description": "Production sync"
  }'

{
  "id": "2e5d9a17-6c34-4b8f-91a2-0d7e3c6b5f48",
  "secret": "whsec_...",
  "url": "https://example.com/webhooks/ontora",
  "events": ["synthesis.completed", "interview.completed"],
  "active": true,
  "created_at": "2026-04-24T18:30:00Z"
}

The secret is only returned on creation. Save it now — you’ll use it to verify every incoming request. See Signing & verification.

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:

curl -X POST https://api.ontora.com/v1/webhook-endpoints/2e5d9a17-6c34-4b8f-91a2-0d7e3c6b5f48/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:

curl https://api.ontora.com/v1/webhook-endpoints/2e5d9a17-6c34-4b8f-91a2-0d7e3c6b5f48/deliveries?limit=20 \
  -H "X-API-Key: $ONTORA_API_KEY"

[
  {
    "id": "9b3f6c28-4e17-4a5d-8c92-3f6b1e0d7a54",
    "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:

curl -X PATCH https://api.ontora.com/v1/webhook-endpoints/2e5d9a17-6c34-4b8f-91a2-0d7e3c6b5f48 \
  -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.

Get started

Core concepts

Guides

MCP server

CLI

Webhooks

How they work

Register an endpoint

Test an endpoint

Inspect deliveries

Retries

Disable an endpoint

Next steps

Event types

Signing & verification

​How they work

​Register an endpoint

​Test an endpoint

​Inspect deliveries

​Retries

​Disable an endpoint

​Next steps

Event types

Signing & verification

How they work

Register an endpoint

Test an endpoint

Inspect deliveries

Retries

Disable an endpoint

Next steps