> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Ontvang een HTTP-callback zodra een project een mijlpaal bereikt, in plaats van te pollen

# 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`.

> [!NOTE]
>
> Elke levering wordt één keer geprobeerd. Er zijn geen nieuwe pogingen; blijf voor belangrijke gebeurtenissen ook de status opvragen.

## Instellen

1. Open de [API-pagina](https://app.voicecheap.ai/page-api) in je VoiceCheap-account.
2. Kies onder **Webhooks** voor **Generate signing secret**. Het geheim met het voorvoegsel `whsec_` wordt maar één keer getoond; kopieer het en bewaar het op uw server.
3. Voer bij **Endpoint URL** een `https`-URL in en kies **Save**.

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

> [!NOTE]
>
> Webhook-URL’s moeten HTTPS op poort 443 gebruiken en naar een openbaar netwerkadres verwijzen. URL’s met inloggegevens of fragmenten, privé- of
> gereserveerde adressen en omleidingen worden geweigerd. Dit geldt voor het accountendpoint en voor URL’s die per project worden ingesteld.

Gebruik `webhooks_get`, `webhooks_update` en `webhooks_delete` via de actie-API of MCP. Gebruik `webhooks_create_secret` alleen via de REST-actie-API. Bewaar het ondertekeningsgeheim veilig wanneer het wordt teruggestuurd; MCP kan deze actie niet uitvoeren of het resultaat ervan opvragen.

### 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:

U kunt `webhookUrl` ook opgeven bij `POST /v1/projects/{projectId}/dub` om de bestemming van een bestaand project bij te werken.

```bash theme={null}
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. |

> [!NOTE]
>
> Er is geen afzonderlijke transcriptiegebeurtenis. Het antwoord op het aanmaken van een project komt voordat de transcriptie is voltooid.
> `project.created` wordt pas verzonden nadat het transcript is opgeslagen; u kunt het dan ophalen met [`POST /v1/projects/{projectId}/transcript`](https://api-docs.voicecheap.ai/docs/nl/api-reference/project-transcript).

## Payload

Elke aflevering is een `POST` met een JSON-body:

```json theme={null}
{
  "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](https://api-docs.voicecheap.ai/docs/nl/api-reference/errors.md). |
| `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.

```js theme={null}
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);
});
```

> [!WARNING]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.