Skip to main content

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 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. 
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"
  }'

{
  "id": "we_...",
  "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/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: 
curl https://api.ontora.com/v1/webhook-endpoints/we_.../deliveries?limit=20 \
  -H "X-API-Key: $ONTORA_API_KEY"

[
  {
    "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: 
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

Event types

Every event Ontora can send, with payload shapes.

Signing & verification

HMAC-SHA256 signature verification — code samples included.