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 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.
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-F [email protected] \
-F webhook_url=https://example.com/hooks/transcript1Sla 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.
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.
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 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.
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));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. Bewaar die ID’s daarom al bij het starten. Zo kun je een ontbrekende callback onderzoeken zonder dezelfde media opnieuw in te sturen.