Webhooks

Webhooks notify your integration when a recording reaches COMPLETED status. 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
Idempotency-Key: setup_2026-08-31

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

Idempotency-Key is required. It must contain 8 to 255 URL-safe characters using letters, numbers, ., _, :, or -. Reusing the same key returns the original subscription instead of creating another one.

The create response includes a secret. Store it securely because 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 subscriptions
`DELETE`	`/webhooks/:id`	Remove a subscription

The list endpoint uses cursor pagination with a default and maximum limit of 50. 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 behaviour

Deliveries run as background jobs with retries
Ardela deduplicates completed dispatches per subscription and recording
Receivers should still use at-least-once handling because a network retry or manual replay can produce a duplicate request
Failed deliveries are retried; permanent failures are logged for operator alerting

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:

{
  "id": "delivery_123",
  "event": "recording.completed",
  "data": {
    "id": "clxxx123",
    "title": "Client Meeting Notes",
    "status": "COMPLETED",
    "priority": "MEDIUM",
    "author": {
      "id": "user123",
      "name": "Jane Doe",
      "email": "jane@firm.com"
    },
    "client": null,
    "matter": null,
    "createdAt": "2026-08-31T09:00:00.000Z",
    "updatedAt": "2026-08-31T09:30:00.000Z",
    "lastSyncedAt": null,
    "syncCount": 0,
    "apiUrl": "/api/v1/recordings/clxxx123"
  }
}

Fetch the full transcript and derived note or document text from https://app.ardela.ai plus the data.apiUrl path using your API key.

Recommended pattern

Webhook wakes your integration for low latency
Poll GET /recordings?syncState=unsynced on a schedule 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