Webhooks

Receive real-time notifications when asynchronous jobs complete, instead of polling. Provide a webhookUrl when you submit a transcription and VoiceMaker will POST a JSON payload to it when the job finishes.

How webhooks work

Pass an HTTPS webhookUrl in your POST /dev/v1/transcribe request.
VoiceMaker processes the job in the background.
When the job completes (or fails), we send a POST request to your URL with a JSON body, and expect a 2xx response within 10 seconds.

Best-effort delivery today

Webhooks are currently delivered once, best-effort, with a 10-second timeout and no automatic retries. Treat them as a fast-path notification and use GET /dev/v1/transcribe/{job_id} as the source of truth. Make your handler idempotent.

Events & payloads

`transcription.completed`

JSON

{
  "event": "transcription.completed",
  "transcription": {
    "id": "trans_1a2b3c4d5e6f7g8h9i0j",
    "status": "COMPLETED",
    "languageRequested": "ha",
    "languageDetected": "ha",
    "transcriptText": "Sannu da zuwa VoiceMaker.",
    "creditsUsed": 150,
    "durationSeconds": 30,
    "completedAt": "2026-03-03T10:33:40Z"
  }
}

`transcription.failed`

JSON

{
  "event": "transcription.failed",
  "transcription": {
    "id": "trans_1a2b3c4d5e6f7g8h9i0j",
    "status": "FAILED",
    "languageRequested": "ha",
    "errorMessage": "Audio could not be decoded.",
    "creditsUsed": null
  }
}

Signature verification & retries Coming soon

Signed webhooks (an X-Webhook-Signature header you can verify) and an automatic retry-with-backoff policy are planned.

Not yet live

Signature verification and retries are not implemented yet. Until they ship, secure your endpoint with a hard-to-guess URL or a shared secret query parameter, validate the payload shape, and reconcile against the job result endpoint.