Webhooks And Async Delivery

Agent submits transcripts with webhook_url=https://app.example.com/aai-hook, webhook_auth_header_name='X-AAI-Secret', webhook_auth_header_value='<long random secret>'.

AssemblyAI POSTs to webhook_url with the configured header name carrying the configured value verbatim. Receiver must check the header name AND value match the expected shared secret before processing. Treat any POST without the header as untrusted.

Receiver returns 502 on first webhook delivery due to a deploy. AssemblyAI retries per its documented retry policy.

AssemblyAI retries non-2xx deliveries over a documented window [REQUIRES-VERIFICATION on exact retry count and interval]. Receiver should return 2xx promptly for accepted events even if downstream processing is async — do not hold the connection for downstream completion.

Webhook body includes transcript_id and status (completed | error). Receiver assumes the body also has full transcript text.

Webhook payload carries identity and status; fetch the full transcript via GET /v2/transcript/{id} after receipt. Treat the webhook as a notification, not as the transcript itself. This decouples webhook size from transcript size and improves reliability.