Webhooks - AirCaps API

Pass webhook_url when you create a transcript. When it finishes, AirCaps sends a POST:

{"event": "transcript.completed", "id": "tr_01k6z...", "status": "completed", "metadata": {"meeting_id": 42}}

event is transcript.completed or transcript.failed. The payload never contains the transcript; fetch it with GET /v1/transcripts/{id}. To add your own header to each delivery, set webhook_auth_header_name and webhook_auth_header_value on the request.

Verify signatures

Deliveries are signed per Standard Webhooks with your account’s webhook secret (whsec_...). Find and rotate it in the console under API keys → Webhook signing secret. Headers: webhook-id, webhook-timestamp, webhook-signature: v1,<base64>.

# pip install standardwebhooks
from standardwebhooks.webhooks import Webhook

wh = Webhook(os.environ["AIRCAPS_WEBHOOK_SECRET"])
event = wh.verify(request_body_bytes, request_headers)   # raises if invalid or older than 5 minutes

Manual check: HMAC-SHA256 with the base64-decoded secret (without whsec_) over {webhook-id}.{webhook-timestamp}.{raw body}, base64-encoded, compared in constant time with the value after v1,. Reject timestamps older than 5 minutes.

Delivery

Reply with any 2xx within 15 seconds.
Failures are retried for about 24 hours (30 s, 2 min, 10 min, 30 min, 1 h, 2 h, 4 h, 8 h, 8 h).
A 4xx other than 408 or 429 stops retries.
webhook-id is stable across retries of one event; use it to deduplicate.
The last HTTP status appears on the transcript as webhook_status_code.