webhook_url when you create a batch. Chariot sends an HTTP POST when a subscribed terminal event occurs. Intermediate transcripts and progress updates are available through polling, not webhooks.
Subscribe to events
transcription.completed, transcription.failed, and transcription.cancelled, one per file. Explicitly include batch events if you also want an aggregate notification. An explicit webhook_events list replaces the default list.
Your destination must be a publicly reachable HTTPS endpoint without URL credentials or fragments. Redirects are not followed. The accepted response includes a webhook_signing_secret for that batch. Save it securely on your server with the batch ID. A matching idempotent resubmission also returns the secret; batch GET responses do not.
Receive a file event
transcription_id matches the accepted response items[].id and the transcription resource id. custom_id echoes your input identifier and is only unique within its batch. The event id identifies the notification, not the audio or transcription.
The notification contains a result path, not the transcript. Fetch that path from https://api.chariot.in using your API key. For a failed or cancelled file, the same route provides its error, billing state, and any saved partial result.
A batch event has counts instead of transcription_id and custom_id. Its result_url points to /v1/asr/batches/{batch_id}. Counts include total and the statuses present in that batch.
Verify the signature
Each delivery includes:
Calculate HMAC-SHA256 over the exact bytes of
<timestamp>.<event_id>.<raw_body>, using the returned batch secret as a UTF-8 string. Do not hex-decode the secret or parse and reserialize the body before verifying it.
id matches Chariot-Event-Id and that the batch belongs to your application.
Acknowledge and deduplicate
After verification, durably record the event and return a2xx response promptly. Process the notification in your own background work if needed. Non-2xx responses and connection failures trigger retries with backoff.
Delivery can happen more than once, and file and batch events can arrive out of order. Deduplicate by Chariot-Event-Id. Retries retain the event ID and body but use a fresh signature timestamp. Acknowledge already-recorded events successfully.
Retries are bounded, so polling remains your recovery path if a notification never arrives. Retrieve the current resource state instead of treating delivery order as processing order.