Webhooks

Webhooks let VoiceCheap notify your server as soon as something happens, so you can stop polling GET /v1/translate/{projectId}/status.

Deliveries are attempted once. There are no retries yet, so keep polling as a safety net for anything you cannot afford to miss. Retries with exponential backoff are planned.

Setup

Open the API page in your VoiceCheap account.
In Webhooks, select Generate signing secret. The secret starts with whsec_ and is shown once — copy it and store it on your server.
Enter your endpoint URL and save it. It must use https.

That is all. Every project you start from then on delivers events to that endpoint.

Overriding the endpoint per request

POST /v1/translate and POST /v1/projects accept an optional webhookUrl field that overrides the account endpoint for that project only. It is handy for sending staging traffic somewhere else:

curl -X POST "https://api.voicecheap.ai/v1/projects" \
  -H "x-api-key: vc_your-key" \
  -F "file=@interview.mp4" \
  -F "targetLanguage=german" \
  -F "webhookUrl=https://staging.your-server.com/voicecheap/webhooks"

The signing secret is always the account secret; only the destination changes.

Events

Event	Fires when
`project.created`	The project exists and its transcript is stored. This is your cue to download the SRT.
`project.creation.failed`	The project could not be created.
`project.translation.completed`	The translation finished and the outputs are ready.
`project.translation.failed`	The translation failed.
`project.lipsync.completed`	Lip sync finished.
`project.lipsync.failed`	Lip sync failed.

There is no separate transcription event. Transcription runs inside project creation, and a project only exists once its transcript is stored — so project.created already means the transcript is ready to fetch with POST /v1/projects/{projectId}/transcript.

Payload

Every delivery is a POST with a JSON body:

{
  "type": "project.created",
  "eventId": "evt_9f2c4b1d8e7a4c3f9b2d1e0a5c6b7d8e",
  "projectId": "7fa7d3a3-4f2b-4c1e-9a6d-2b3c4d5e6f70",
  "workflow": "transcription",
  "status": "success",
  "targetLanguage": "german",
  "error": null,
  "occurredAt": "2026-08-19T09:12:00.000Z"
}

Field	Type	Description
`type`	string	One of the events above.
`eventId`	string	Unique per event. Use it to deduplicate.
`projectId`	string	The project this event belongs to.
`workflow`	string	`transcription` or `translation`.
`status`	string	`success` or `failed`.
`targetLanguage`	string	Present only on language specific events.
`error`	object \| null	On `*.failed` events, the same `{ code, message }` shape as the REST API. See Error Codes.
`occurredAt`	string	ISO 8601 timestamp.

The payload is intentionally thin. Call the REST API for the content itself.

Verifying the signature

Every delivery carries these headers:

Header	Description
`X-VoiceCheap-Signature`	`sha256=<hex>` — HMAC-SHA256 of the payload, keyed by your signing secret.
`X-VoiceCheap-Timestamp`	Unix seconds, included in the signed string so you can reject replays.
`X-VoiceCheap-Event-Id`	Same value as `eventId` in the body, useful in support requests.

The signature covers <timestamp>.<raw body>, so it is different on every delivery and proves both that the request came from VoiceCheap and that the body was not modified in transit.

import crypto from 'crypto';
import express from 'express';

const app = express();

// The raw body is required: parsing and re-serializing changes the bytes and the signature will
// never match. This is the single most common cause of failed verification.
app.post('/voicecheap/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  const timestamp = req.header('X-VoiceCheap-Timestamp');
  const signature = req.header('X-VoiceCheap-Signature')?.replace('sha256=', '') ?? '';

  // Reject anything older than five minutes.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return res.status(400).send('Stale timestamp');
  }

  const expected = crypto
    .createHmac('sha256', process.env.VOICECHEAP_WEBHOOK_SECRET)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  const isValid =
    expected.length === signature.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

  if (!isValid) return res.status(401).send('Invalid signature');

  const event = JSON.parse(rawBody);
  // Acknowledge quickly, then process asynchronously.
  res.status(200).send('ok');
  handleEvent(event);
});

Verify the signature before trusting a delivery. Your endpoint is a public URL, and the signature is what distinguishes a real VoiceCheap event from anything else that reaches it.

Responding

Reply with any 2xx status to acknowledge. Answer within 10 seconds — acknowledge first and do the work afterwards, rather than processing before you reply. A non-2xx response or a timeout is recorded as a failed delivery and, for now, is not retried.

Rotating the secret

Select Rotate on the API page to generate a new secret. The previous one stops working immediately, so deploy the new secret to your server as soon as you rotate. Deleting the webhook removes both the endpoint and the secret, and deliveries stop.

Overview

Transcription

Translation

Reference

Webhooks

Webhooks

Setup

Overriding the endpoint per request

Events

Payload

Verifying the signature

Responding

Rotating the secret

​Webhooks

​Setup

​Overriding the endpoint per request

​Events

​Payload

​Verifying the signature

​Responding

​Rotating the secret

Webhooks

Setup

Overriding the endpoint per request

Events

Payload

Verifying the signature

Responding

Rotating the secret