Receive and verify Recall.ai bot status-change webhooks (HMAC signature verification)

Documented steps

1. In the regional Recall dashboard's Webhooks tab (e.g. https://us-east-1.recall.ai/dashboard), click 'Add Endpoint' and register your public HTTPS URL. Ref: https://docs.recall.ai/docs/status-change-webhooks-setup-verification
2. Subscribe the endpoint to the event types you need (bot status change, recording status, transcript status, Calendar V2 events); unsubscribed types are never delivered. Ref: https://docs.recall.ai/reference/webhooks-overview
3. Get the verification secret from Developers > API Keys & Secrets in the dashboard; it starts with the 'whsec_' prefix and covers webhooks, websockets and callbacks. Ref: https://docs.recall.ai/docs/authenticating-requests-from-recallai
4. On each POST, read headers webhook-id, webhook-timestamp, webhook-signature. Workspaces created before 2025-12-15 receive the legacy svix-id / svix-timestamp / svix-signature headers and may have separate per-endpoint secrets - accept either header set (headers['webhook-id'] ?? headers['svix-id']).
5. Strip the 'whsec_' prefix from the secret and base64-decode the remainder to get the signing key.
6. Build the signing string exactly as `${msgId}.${msgTimestamp}.${payloadStr}` using the RAW request body, not re-serialized JSON.
7. HMAC-SHA256 the signing string with the decoded secret, base64-encode the result, and compare timing-safely against the signature header, which may contain several space-separated 'v1,<sig>' entries during secret rotation.
8. Only after verification passes, parse the body: {"event": "bot.status_change", "data": {"bot_id": ..., "status": {"code": ..., "sub_code": ..., "message": ..., "created_at": ..., "recording_id": ...}}}. Ref: https://docs.recall.ai/docs/bot-status-change-events
9. Branch on status.code: ready, joining_call, in_waiting_room, in_call_not_recording, recording_permission_allowed, recording_permission_denied, in_call_recording, call_ended, done, fatal, analysis_done, analysis_failed, media_expired. Use status.sub_code for the machine-readable reason.
10. Return 2xx quickly and process asynchronously. Failed deliveries retry on the Svix schedule (immediate, 5s, 5m, 30m, 2h, 5h, 10h twice); endpoints failing continuously for 5 days are auto-disabled.
11. To debug one bot, filter dashboard messages by the tag bot.id-{BOT_ID}. Ref: https://docs.recall.ai/docs/faq-webhooks