Webhooks: HMAC Signature, Redeliveries, and Best Practices
How to receive transcription results via webhook: HMAC-SHA256 signature, X-VPT-Signature and X-VPT-Event headers, 6 redelivery attempts with backoff.
Instead of polling the API to find out whether the transcription is done, you provide a webhook_url in the request and VoxScriber sends a POST to your server when the job finishes — whether successfully or with an error. This is the recommended way to integrate: fewer requests and the result arrives right away.
How it works
- You send the audio with a
webhook_url(must behttps). - When processing finishes, we make a POST to that URL with the result.
- Your server responds with a
2xxstatus to confirm receipt.
Each delivery carries two identification headers:
| Header | Content |
|---|---|
X-VPT-Event | The event type (completion, failure, etc.) |
X-VPT-Signature | HMAC-SHA256 signature of the delivery |
Always validate the signature before trusting the content: compute the HMAC-SHA256 of the received body and compare it with the value in the X-VPT-Signature header. Requests without a valid signature must be discarded—anyone can discover your endpoint URL.
Automatic redeliveries
If your endpoint is down or takes too long, we try again:
- Timeout per attempt: 15 seconds.
- Maximum attempts: 6.
- Wait between attempts (backoff): 5 min → 30 min → 2 h → 6 h → 24 h.
All deliveries are persisted on our side, so you can audit the history with support if something goes missing.
Respond to the webhook immediately with 200 and process the content asynchronously (queue, job). If your processing takes longer than 15 seconds, the delivery counts as a failure and goes into the redelivery queue—and you may end up receiving the same event twice. Treat events idempotently.
You always receive an outcome
Stuck jobs don't disappear silently:
- A queued job stuck for more than 10 minutes is automatically re-enqueued.
- A processing job stuck for more than 60 minutes is marked as failed—and triggers an error webhook to your URL.
In other words: for every audio you send, your system receives a final callback, whether success or failure.
FAQ
My server went down. Did I lose the result?
Probably not: there are up to 6 attempts spread over ~24 hours. If all fail, the delivery history stays recorded—contact support to reprocess.
Can I use an http URL (without TLS)?
No. For security, we only accept https URLs, no redirects, and internal/private addresses are blocked.
How do I tell a success webhook from an error one?
By the X-VPT-Event header, which identifies the event type, and by the content of the delivery body.
What does my endpoint need to respond?
Any 2xx status within 15 seconds. Other statuses (or timeouts) count as failures and trigger redelivery.
Related articles
Still stuck? Open a ticket — our team replies quickly.