Webhooks

Webhooks notify your integration when a recording reaches COMPLETED status — faster than polling alone. Polling remains the recovery source of truth if a webhook is missed.

Scope required: manage:webhooks

Each workspace can register up to 50 webhook subscriptions.

POST /api/v1/webhooks
Authorization: Bearer ardela_pk_...
Content-Type: application/json

{
  "url": "https://example.com/ardela/webhooks",
  "events": ["recording.completed"]
}

The create response includes a secret shown once. Store it securely — you need it to verify signatures.

Supported events

Event	When fired
`recording.completed`	A recording transitions to `COMPLETED`

Manage subscriptions

Method	Path	Description
`GET`	`/webhooks`	List active subscriptions
`DELETE`	`/webhooks/:id`	Remove a subscription

Webhook URLs are validated when created and revalidated before each delivery attempt.

Verify signatures

Each delivery includes headers you must verify before processing:

Header	Description
`x-ardela-signature`	`sha256=<hmac>` of `timestamp + "." + raw_body`
`x-ardela-timestamp`	Unix timestamp (seconds)
`x-ardela-event`	Event type (e.g. `recording.completed`)
`x-ardela-delivery`	Delivery ID for debugging

Compute the expected signature:

HMAC-SHA256(secret, timestamp + "." + raw_request_body)

Compare to the value in x-ardela-signature (after the sha256= prefix). Reject requests with invalid or stale signatures.

Delivery behavior

Deliveries run as background jobs with retries
Delivery is idempotent per workspace/recording — destinations that already received an event are skipped
Failed deliveries are retried; permanent failures are logged for operator alerting
If the job queue is temporarily unavailable, pending dispatches retry every 5 minutes

Inspect deliveries

GET /api/v1/webhooks/deliveries?status=FAILED&limit=50

Filter by status and subscriptionId. Returns at most 50 rows.

Replay a failed delivery

POST /api/v1/webhooks/deliveries/:id/replay

Re-attempts a specific failed delivery.

Webhook payload

Webhook bodies include recording metadata and a link to fetch full content:

{
  "event": "recording.completed",
  "recording": {
    "id": "clxxx123",
    "title": "Client Meeting Notes",
    "status": "COMPLETED"
  },
  "apiUrl": "/api/v1/recordings/clxxx123"
}

Fetch full transcript and note content from the apiUrl path on the API base URL using your API key.

Recommended pattern

Webhook wakes your integration for low latency
Poll GET /recordings?syncState=unsynced on a schedule (every 5–15 minutes) to catch anything missed
Fetch GET /recordings/:id for full content
File in your external system
Mark filed with POST /recordings/:id/filings

On this page