Webhooks

Met webhooks kan VoiceCheap je server op de hoogte stellen zodra er iets gebeurt, zodat je kunt stoppen met pollen GET /v1/translate/{projectId}/status.

Afleveringen worden één keer geprobeerd. Er zijn nog geen nieuwe pogingen, dus blijf pollen als vangnet voor alles wat je niet mag missen. Nieuwe pogingen met exponentiële uitstel zijn gepland.

Instellen

Open de API-pagina in je VoiceCheap-account.
Selecteer bij Webhooks de optie Generate signing secret. Het geheim begint met whsec_ en wordt één keer getoond — kopieer het en sla het op je server op.
Voer je endpoint URL in en sla deze op. Deze moet https gebruiken.

Dat is alles. Elk project dat je vanaf dat moment start, levert gebeurtenissen aan dat eindpunt.

Het eindpunt per verzoek overschrijven

POST /v1/translate en POST /v1/projects accepteren een optioneel webhookUrl-veld dat het accounteindpunt alleen voor dat project overschrijft. Dit is handig om staging-verkeer ergens anders heen te sturen:

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"

Het ondertekeningsgeheim is altijd het accountgeheim; alleen de bestemming verandert.

Gebeurtenissen

Gebeurtenis	Wordt geactiveerd wanneer
`project.created`	Het project bestaat en het transcript is opgeslagen. Dit is je teken om de SRT te downloaden.
`project.creation.failed`	Het project kon niet worden aangemaakt.
`project.translation.completed`	De vertaling is voltooid en de uitvoer is klaar.
`project.translation.failed`	De vertaling is mislukt.
`project.lipsync.completed`	Lipsynchronisatie voltooid.
`project.lipsync.failed`	Lipsynchronisatie mislukt.

Er is geen afzonderlijke transcriptiegebeurtenis. Transcriptie wordt uitgevoerd tijdens het aanmaken van een project, en een project bestaat pas zodra het transcript is opgeslagen — dus project.created betekent al dat het transcript klaar is om op te halen met POST /v1/projects/{projectId}/transcript.

Payload

Elke aflevering is een POST met een 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"
}

Veld	Type	Beschrijving
`type`	string	Een van de bovenstaande gebeurtenissen.
`eventId`	string	Uniek per gebeurtenis. Gebruik dit om te ontdubbelen.
`projectId`	string	Het project waar deze gebeurtenis bij hoort.
`workflow`	string	`transcription` of `translation`.
`status`	string	`success` of `failed`.
`targetLanguage`	string	Alleen aanwezig bij taalspecifieke gebeurtenissen.
`error`	object \| null	Bij `*.failed`-gebeurtenissen, dezelfde `{ code, message }`-vorm als de REST API. Zie Foutcodes.
`occurredAt`	string	ISO 8601 tijdstempel.

De payload is bewust beknopt. Roep de REST API aan voor de inhoud zelf.

De handtekening verifiëren

Elke aflevering bevat deze headers:

Header	Beschrijving
`X-VoiceCheap-Signature`	`sha256=<hex>` — HMAC-SHA256 van de payload, gesleuteld met uw ondertekeningsgeheim.
`X-VoiceCheap-Timestamp`	Unix-seconden, opgenomen in de ondertekende string zodat u herhalingen kunt afwijzen.
`X-VoiceCheap-Event-Id`	Dezelfde waarde als `eventId` in de body, nuttig bij ondersteuningsverzoeken.

De handtekening dekt <timestamp>.<raw body>, dus deze is bij elke aflevering anders en bewijst zowel dat het verzoek van VoiceCheap kwam als dat de body tijdens het transport niet is gewijzigd.

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);
});

Verifieer de handtekening voordat u een aflevering vertrouwt. Uw eindpunt is een openbare URL, en de handtekening is wat een echte VoiceCheap-gebeurtenis onderscheidt van al het andere dat het bereikt.

Reageren

Antwoord met een 2xx-status om te bevestigen. Antwoord binnen 10 seconden — bevestig eerst en doe het werk daarna, in plaats van te verwerken voordat u antwoordt. Een niet-2xx-antwoord of een time-out wordt geregistreerd als een mislukte aflevering en wordt vooralsnog niet opnieuw geprobeerd.

Het geheim roteren

Selecteer Roteren op de API-pagina om een nieuw geheim te genereren. Het vorige stopt onmiddellijk met werken, dus implementeer het nieuwe geheim op uw server zodra u roteert. Het verwijderen van de webhook verwijdert zowel het eindpunt als het geheim, en afleveringen stoppen.

Overzicht

Transcriptie

Vertaling

Referentie

Webhooks

Webhooks

Instellen

Het eindpunt per verzoek overschrijven

Gebeurtenissen

Payload

De handtekening verifiëren

Reageren

Het geheim roteren

​Webhooks

​Instellen

​Het eindpunt per verzoek overschrijven

​Gebeurtenissen

​Payload

​De handtekening verifiëren

​Reageren

​Het geheim roteren

Webhooks

Instellen

Het eindpunt per verzoek overschrijven

Gebeurtenissen

Payload

De handtekening verifiëren

Reageren

Het geheim roteren