Webhooks
Get a signed POST to your server when a transcription is processing, completes or fails, instead of polling.
Overview
When you provide a webhook_url in your transcription request, we POST progress and result events to that URL as the job moves through the pipeline. Webhooks are signed with HMAC-SHA256 using your key's webhook signing secret, so you can verify they came from Scriptivox. A delivery your server does not accept is retried with backoff, 8 tries over about 10¾ h, and every event carries a stable ID so you can drop repeats.
Webhooks fire for both upload-based and URL-based transcription flows. The webhook_url field is optional. If omitted, no webhooks are sent and you should poll GET /v1/transcribe/{id} instead.
You can also set a default webhook URL in your account settings that is used for any transcription that does not specify one in the request body.
Webhook URLs must use https://. A request with an http:// webhook_url is refused with INVALID_REQUEST, and so are private and internal addresses.
Setting up webhooks
Pass a webhook_url when starting a transcription:
requests.post("https://api.scriptivox.com/v1/transcribe",headers={"Authorization": "sk_live_YOUR_KEY"},json={"upload_id": "abc-123","webhook_url": "https://your-server.com/webhook"})
Check your endpoint first
Before going live, send yourself a test event. It is signed with the key's secret and carries the same headers as a real event, so it also tests your signature check:
- In the dashboard: Settings → Webhook deliveries → choose the key → Send test event.
- With the API:
POST /v1/webhooks/testwith{"url": "https://…"}(or no body, to use your default webhook URL). The answer tells you what your server returned.
Webhook events
Every job sends transcription.processing once the file has been checked and sent for transcription, then exactly one of transcription.completed or transcription.failed when the job ends. URL jobs also send transcription.downloading when the download starts. The created state is visible in GET /v1/transcribe/{id} polling but does not send a webhook.
transcription.processing
Sent when the audio file has been downloaded or uploaded and checked, and the transcription job has been submitted for processing. Includes the measured duration and the reserved cost.
{"event": "transcription.processing","transcription_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901","status": "processing","duration_seconds": 120,"cost_cents": 0.666667}
transcription.completed
Sent when a transcription finishes successfully. Includes the full result, the same as GET /v1/transcribe/{id} returns.
{"event": "transcription.completed","transcription_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901","status": "completed","duration_seconds": 120,"cost_cents": 0.666667,"result": {"full_transcript": "Hello, thanks for joining...","language": "en","duration_seconds": 120,"speakers": ["SPEAKER 1", "SPEAKER 2"],"utterances": [{"start": 0.5,"end": 3.2,"text": "Hello, thanks for joining the call today.","speaker": "SPEAKER 1","confidence": 0.95,"words": [...]}]}}
transcription.failed
Sent any time a transcription ends in the failed state. Reserved balance is automatically released so a failed job costs $0.
This event covers every failure surface: URL download/validation errors, insufficient balance, internal errors, transcription failures, and cleanup-timeout failures (when a job sits stuck in created, downloading, or processing past its threshold). You will receive at most one transcription.failed event per transcription, so a single handler can cover all failure modes. Branch on error.code (see API reference: error codes) for code-specific behavior.
error.message is a sanitized, customer-safe string; we don't forward raw internal errors. For PROCESSING_ERROR cases where the message is generic, retrying is usually the right next step.
{"event": "transcription.failed","transcription_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901","status": "failed","error": {"code": "PROCESSING_ERROR","message": "Failed to process audio file"}}
transcription.downloading
URL jobs only: sent once when we start downloading the file from your URL. It is tried once and not retried: a late "downloading" would tell you nothing.
{"event": "transcription.downloading","transcription_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901","status": "downloading"}
webhook.test
Sent only when you ask for a test event (dashboard or POST /v1/webhooks/test). One try. It is not about a real job, so answer it with a 2xx and do nothing else.
{"event": "webhook.test","test": true,"message": "This is a test event from Scriptivox. Answer with any 2xx status to confirm your endpoint works.","created_at": "2026-11-09T16:00:00.000Z"}
Events summary
| Event | When | Flows | Retried |
|---|---|---|---|
| transcription.processing | File checked, sent for transcription | Both | Yes, until the job's final event is sent |
| transcription.completed | Transcription finished successfully | Both | Yes, up to 8 tries |
| transcription.failed | Download, validation, or processing failed | Both | Yes, up to 8 tries |
| transcription.downloading | Download from your URL started | URL | No, one try |
| webhook.test | You asked for a test event | n/a | No, one try |
Answer 2xx to any event you do not handle: new event types may be added.
Verifying webhook signatures
Your webhook signing secret
Each API key has its own webhook signing secret, a random string that starts with whsec_. Find it on the API Keys page: choose Show webhook secret under the key. Webhooks for a job are signed with the secret of the key that created the job.
- Keep it on your server only, like the API key. It is not the API key and cannot be worked out from it.
- Regenerate (on the same page) replaces it at once: the old secret stops working, so update your server straight away.
Every webhook request includes these headers:
| Header | Description |
|---|---|
X-Scriptivox-Signature | HMAC-SHA256 hex digest of the signed payload |
X-Scriptivox-Timestamp | Unix timestamp (seconds, as a string) of when this try was sent |
X-Scriptivox-Delivery | ID of the event. The same on every retry and resend of that event: use it to drop repeats |
X-Scriptivox-Attempt | Which try this is: 1 for the first, up to 8 for automatic retries |
POST /webhooks/scriptivox HTTP/1.1Content-Type: application/jsonUser-Agent: scriptivox-webhook/1X-Scriptivox-Signature: 5d2f0c4e9b1a…X-Scriptivox-Timestamp: 1794240000X-Scriptivox-Delivery: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4fX-Scriptivox-Attempt: 2
Signing formula
signing_secret: your key's webhook signing secret, the whole string includingwhsec_, as UTF-8signed_payload = f"{timestamp}.{body}": body is the exact raw JSON request body, byte-for-bytesignature = HMAC_SHA256_hex(signing_secret, signed_payload): sent asX-Scriptivox-Signature
Reject any request whose X-Scriptivox-Timestamp is more than 5 minutes old to prevent replay attacks. Each retry is signed again with a fresh timestamp, so retries pass this check.
import hmacimport hashlibimport osimport time# Your key's webhook signing secret (API Keys page > Show webhook secret)WEBHOOK_SECRET = os.environ["SCRIPTIVOX_WEBHOOK_SECRET"] # "whsec_..."def verify_webhook(body: bytes, signature: str, timestamp: str) -> bool:if not signature or not timestamp:return False# Check timestamp is recent (within 5 minutes)now = int(time.time())if abs(now - int(timestamp)) > 300:return Falsemessage = f"{timestamp}.{body.decode()}"expected = hmac.new(WEBHOOK_SECRET.encode(),message.encode(),hashlib.sha256).hexdigest()return hmac.compare_digest(expected, signature)# In your webhook handler:# signature = request.headers.get("X-Scriptivox-Signature", "")# timestamp = request.headers.get("X-Scriptivox-Timestamp", "")# is_valid = verify_webhook(request.body, signature, timestamp)
Delivery behavior
What counts as delivered
- Any
2xxstatus within 10 seconds means delivered. Retries for that event stop. 410 Gonemeans "stop": we make no more tries for that event.- Anything else is retried: another status code (
4xxother than 410,5xx, a3xxwe do not follow), no answer within 10 seconds, or no connection at all.
Retry schedule
A failed event is retried after these waits, counted from the previous try:
| Try | Wait before it | About this long after the first try |
|---|---|---|
| 1 | none: sent as soon as the event happens | 0 |
| 2 | 30 seconds | 30 s |
| 3 | 2 minutes | 2.5 min |
| 4 | 10 minutes | 12.5 min |
| 5 | 30 minutes | 43 min |
| 6 | 60 minutes | 1 h 43 min |
| 7 | 3 hours | 4 h 43 min |
| 8 | 6 hours | 10 h 43 min |
After the 8th failed try the event is marked failed and not sent again on its own; you can still resend it (below). Retries can be up to a minute later than the times above.
Duplicates and order
- Deduplicate by
X-Scriptivox-Delivery. The same event can reach you more than once: your server answered after the 10-second limit, a network error hid your 2xx from us, or you resent it. Store the IDs you have handled and answer2xxto a repeat without doing the work again. - Order is not guaranteed once retries are involved. Use the
statusfield, not arrival order. Atranscription.processingstill waiting for a retry when the job ends is dropped, so it never arrives after the job's final event.
Delivery log and resend
- The dashboard shows the last 50 deliveries per API key: Settings → Webhook deliveries, with each event's status, number of tries and the last response code. Deliveries are kept for 30 days.
- Resend any delivery from that list, or a job's final event with
POST /v1/transcribe/{id}/webhook/resend. A resend is one try made at once, with the sameX-Scriptivox-Delivery; automatic retries still left carry on as scheduled.
Other details
- One redirect followed. If your endpoint returns a 3xx response with a
Locationheader, the same body and signature/timestamp headers are re-POSTed to the resolved URL exactly once. Onlyhttpsdestinations are followed; any otherLocationis not, and the try counts as failed. - User-Agent on every request starts with
scriptivox-webhook/1(our hosting adds a suffix after it). - Transcriptions complete normally regardless of webhook delivery status; webhook health does not affect billing or job state.
For anything that must never be missed, also poll GET /v1/transcribe/{id} as a fallback, for example for jobs you have not heard about after a few hours. Live API uptime is published at status.scriptivox.com.
Best practices
- Return 2xx quickly: Acknowledge the webhook within 10 seconds and do any heavy work asynchronously. A slower answer counts as a failed try and is retried.
- Always verify signatures: Check the HMAC-SHA256 signature against the raw body before trusting any payload.
- Check timestamps: Reject webhooks with
X-Scriptivox-Timestampolder than 5 minutes to prevent replay attacks. - Be idempotent: Deduplicate by
X-Scriptivox-Delivery, and act on thestatusfield rather than on arrival order. - Use HTTPS: Webhook URLs must be
https://. For local development, expose your server through an HTTPS tunnel such as ngrok. - Answer 410 to stop: If an endpoint is retired for good, answering
410 Gonestops further tries for that event. - Poll as a fallback: Webhooks are retried for about 10¾ h; polling
GET /v1/transcribe/{id}covers a longer outage on your side.