# Een transcriptie-webhook met handtekening voor je backend

> Met een transcriptie-webhook krijg je een ondertekende POST zodra je transcriptie klaar is of mislukt. Geef webhook_url mee; pollen is niet nodig.

Canonical: https://transcript1.com/nl/features/transcriptie-webhook
Language: nl
Last updated: 2026-10-19

Met een transcriptie-webhook hoeft je code niet steeds naar de status te vragen. Geef webhook_url mee wanneer je een transcriptie start. Zodra die klaar is of mislukt, sturen we een ondertekende POST naar je endpoint.

- transcription.completed en transcription.failed
- Elke melding ondertekend met HMAC-SHA256
- Maximaal 6 afleverpogingen, met oplopende wachttijd

## Ontvang de melding en haal daarna de tekst op

### Klaar of mislukt

Je ontvangt transcription.completed of transcription.failed. Bij een geannuleerde transcriptie sturen we geen webhook.

### Controleer wie de melding verstuurt

X-Transcript1-Signature bevat een tijdstempel en HMAC-SHA256-handtekening van de onbewerkte body. De sleutel is het whsec_-secret van je team.

### Een gemiste melding krijgt een nieuwe poging

Elke 2xx-response telt als ontvangen. Anders proberen we opnieuw na wachttijden van 2, 4, 8, 16 en 32 minuten: maximaal 6 pogingen in totaal.

### Alleen een openbaar HTTPS-endpoint

De URL moet HTTPS gebruiken en naar een openbaar adres verwijzen. We controleren dat bij het starten van de transcriptie en bij elke afleverpoging.

### De melding blijft klein

Je krijgt het transcriptieobject zonder de transcripttekst. Haal de tekst daarna met het ID op, in het formaat dat je nodig hebt.

## Geef webhook\_url mee bij het starten

De optie werkt bij ondersteunde videolinks, uploadreserveringen en als formulierveld bij een upload in één request. Combineren met reuse_recent kan niet. Bekijk de [webhookparameters](https://transcript1.com/nl/docs/webhooks#set-a-webhook-url) voordat je de URL toevoegt.

Een webhook past bij werk dat doorgaat nadat het eerste request al terug is: interviews verwerken, een afleveringenarchief opbouwen of videotranscripts verzamelen. Bewaar het transcriptie-ID bij de taak in je eigen systeem. Zo kun je de callback aan de juiste gebruiker en actie koppelen.

Gebruik meteen je definitieve openbare HTTPS-endpoint, niet een adres dat doorstuurt. localhost werkt niet als ontvanger. De bestemming wordt ook bij de aflevering opnieuw gecontroleerd. Met de bestandsupload uit het voorbeeld kun je de hele route testen met een opname die je zelf beheert.

### Een upload starten met webhook

```
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -F file=@episode.mp3 \
  -F webhook_url=https://example.com/hooks/transcript1
```

## Sla het event op en antwoord snel

data bevat het transcriptieobject, zonder de tekst. Gebruik data.id samen met type om dubbele meldingen te herkennen. Daarna kun je het afgeronde [transcript via de API ophalen](https://transcript1.com/nl/docs/api-reference#get-a-transcription).

Houd rekening met meerdere afleveringen van hetzelfde event. Je handler kan de melding al verwerkt hebben terwijl de response pas na de time-out van 10 seconden aankomt. Bewaar de combinatie van transcriptie-ID en eventtype voordat je bijvoorbeeld een artikel publiceert of een gebruiker een bericht stuurt.

Controleer eerst de handtekening. Sla het event daarna duurzaam op of zet het in je wachtrij en antwoord snel met 2xx. Haal de tekst in een achtergrondtaak op via data.id. Bij transcription.failed lees je data.error en werk je de taakstatus bij. Annuleer je zelf een transcriptie, pas dan ook zelf de status aan: daarvoor volgt geen callback.

### POST naar je webhook-URL

```
X-Transcript1-Signature: t=<unix seconds>,v1=<hex digest>

{
  "type": "transcription.completed",
  "created_at": "2026-10-13T09:30:04.000Z",
  "data": {
    "id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
    "object": "transcription",
    "status": "completed",
    "transcript_source": "speech_to_text",
    "billed_minutes": 4,
    "error": null
  }
}
```

## Controleer de webhook met HMAC-SHA256

Voeg t, een punt en de onbewerkte body samen en bereken daarvan de HMAC-SHA256 met je whsec_-secret. Vergelijk de handtekeningen in constante tijd en wijs tijdstempels af die te ver van de huidige tijd liggen. De [verificatiegids](https://transcript1.com/nl/docs/webhooks#verify-the-signature) bevat alle controles en complete voorbeelden.

Lees de body zoals die binnenkomt, vóór je JSON-parser eraan zit. JSON opnieuw serialiseren kan witruimte of de sleutelvolgorde veranderen; de handtekening klopt dan niet meer. Valideer de header en het tijdstempel, controleer of de digests even lang zijn en vergelijk ze in constante tijd. Parse de JSON pas als de controle slaagt.

Het korte Node.js-voorbeeld gaat ervan uit dat t en v1 al uit de header zijn gehaald en gevalideerd. De volledige Node.js- en Python-voorbeelden gebruiken een tijdstolerantie van 5 minuten. Gebruik het hele secret, inclusief whsec_. Roteer je het teamsecret, dan geldt de nieuwe sleutel meteen voor volgende afleveringen.

### Node.js

```
const expected = crypto
  .createHmac('sha256', secret)
  .update(`${t}.${rawBody}`)
  .digest('hex');
const valid = v1.length === expected.length
  && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
```

- [Volledige voorbeelden voor handtekeningcontrole](https://transcript1.com/nl/docs/webhooks)

## Test juist de fouten en dubbele meldingen

Test een geslaagde transcriptie, een mislukte transcriptie en een dubbel event. Dezelfde melding mag niet tweemaal publiceren. Een mislukte transcriptie mag ook niet in een publicatiestap terechtkomen die tekst verwacht. Test een ongeldige handtekening apart van fouten in je eigen verwerking.

Elke afleverpoging heeft een time-out van 10 seconden. Wacht dus niet met antwoorden tot een zoekindex of model klaar is. Een eigen duurzame wachtrij helpt je om dat vervolgwerk opnieuw te proberen nadat je de webhook hebt bevestigd. Onze afleverpogingen vervangen die wachtrij niet.

Bij een niet-2xx-response, verbindingsfout of time-out volgen nieuwe pogingen na 2, 4, 8, 16 en 32 minuten. Na maximaal 6 pogingen stoppen we. Redirects volgen we niet. Log het taak-ID, het eventtype en of de aflevering lukte, maar nooit het signing secret.

Mis je na de laatste poging nog een melding, lees dan de bekende ID’s via het [transcriptie-endpoint](https://transcript1.com/nl/docs/api-reference#get-a-transcription). Bewaar die ID’s daarom al bij het starten. Zo kun je een ontbrekende callback onderzoeken zonder dezelfde media opnieuw in te sturen.

## Veelgestelde vragen

### Waar vind ik mijn signing secret?

Op de dashboardpagina “Webhooks”. Het begint met whsec_ en geldt voor je team. Je kunt het daar op elk moment roteren.

### Wat als mijn endpoint even niet bereikbaar is?

We proberen de melding opnieuw af te leveren, met oplopende wachttijden. Er zijn maximaal 6 pogingen, verspreid over ongeveer een uur. Per poging wachten we maximaal 10 seconden. Redirects volgen we niet.

### Kan ik een webhook instellen via MCP?

Nee, webhooks zijn alleen beschikbaar via de REST API. De MCP-tools wachten op de transcriptie of geven een ID terug om later verder te lezen.

## Lees ook

- [Webhooks instellen (documentatie)](https://transcript1.com/nl/docs/webhooks)
- [Audio- en video-API](https://transcript1.com/nl/features/speech-to-text-api)
- [AI-agents en LLM-pipelines](https://transcript1.com/nl/use-cases/transcripties-voor-ai-agents)