webhook_url beim Erstellen mitsenden
Die Option funktioniert bei Videolinks, Upload-Reservierungen und als Formularfeld beim direkten Datei-Upload. Mit reuse_recent lässt sie sich nicht kombinieren. Die Webhook-Doku zeigt die Request-Parameter.
Webhooks passen zu Hintergrundaufgaben, die nach dem ursprünglichen Request weiterlaufen: Interviews verarbeiten, ein Episodenarchiv aufbauen oder Transkripte mehrerer Social-Media-Videos sammeln. Speichere die Transkriptions-ID bei deinem eigenen Auftrag. Dann kannst du den Callback der richtigen Aktion zuordnen.
Gib den endgültigen öffentlichen HTTPS-Endpoint an. Weiterleitungen folgen wir nicht, localhost ist kein gültiger Empfänger. Das Ziel prüfen wir beim Anlegen und erneut vor der Zustellung. Im Beispiel nutzt du eine eigene Aufnahme, um den Ablauf mit einer kontrollierbaren Quelle zu testen.
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/transcript1Schnell bestätigen und doppelte Events abfangen
data enthält das Transkriptionsobjekt ohne den Text. Nutze data.id zusammen mit type, um doppelte Zustellungen zu erkennen. Das fertige Transkript liest du anschließend über die API.
Ein Event kann mehrfach ankommen. Dein Handler kann es bereits verarbeitet haben, obwohl seine Antwort erst nach dem Timeout von 10 Sekunden eintrifft. Speichere nach erfolgreicher Signaturprüfung die Kombination aus Transkriptions-ID und Eventtyp dauerhaft, bevor du etwa einen Artikel veröffentlichst oder jemanden benachrichtigst. Bestätige nach dem sicheren Speichern oder Einreihen in eine Queue zügig mit 2xx.
Lade das Transkript mit data.id in einer Hintergrundaufgabe. Bei transcription.failed liest du data.error und aktualisierst den Status in deiner App. Einen Abbruch musst du im eigenen Abbruchablauf verbuchen, denn dafür kommt kein 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
}
}Webhook-Signatur mit HMAC-SHA256 prüfen
Berechne die HMAC-SHA256-Signatur über t, einen Punkt und den unveränderten Body. Nutze dafür dein whsec_-Secret. Vergleiche die Signaturen in konstanter Zeit und lehne deutlich veraltete Zeitstempel ab. Die vollständige Prüfanleitung umfasst auch die Validierung des Headers.
Lies den Body, bevor ein JSON-Parser ihn verändert. Wenn du geparstes JSON erneut serialisierst, können sich Leerzeichen und die Reihenfolge der Felder ändern. Dann stimmt die Signatur nicht mehr. Validiere Zeitstempel und Header, vergleiche gleich lange Digests in konstanter Zeit und parse das JSON erst nach erfolgreicher Prüfung.
Das kurze Beispiel setzt voraus, dass t und v1 schon ausgelesen und validiert sind. Die vollständigen Beispiele für Node.js und Python berücksichtigen eine Zeitstempeltoleranz von 5 Minuten. Verwende das ganze Secret einschließlich whsec_. Wenn du das Team-Secret rotierst, gilt der neue Schlüssel sofort für weitere Zustellungen.
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));Fehlerfälle testen, bevor der Callback etwas veröffentlicht
Teste ein abgeschlossenes Event, ein fehlgeschlagenes Event und eine doppelte Zustellung. Derselbe Abschluss darf keine zweite Veröffentlichung auslösen. Ein Fehler darf nicht in einen Ablauf zum Abrufen und Veröffentlichen eines gar nicht vorhandenen Transkripts geraten. Teste ungültige Signaturen getrennt von Fehlern in deiner Verarbeitung.
Jeder Zustellversuch hat ein Timeout von 10 Sekunden. Warte mit der Bestätigung nicht auf langsame Indizierung oder KI-Aufrufe. Sichere das Event und erledige diese Arbeit über deine eigene Queue. Deren Wiederholungen liegen bei deiner Anwendung; unsere Zustellversuche ersetzen sie nicht.
Bei Antworten außerhalb von 2xx, Verbindungsfehlern oder Timeouts warten wir 2, 4, 8, 16 und 32 Minuten vor dem nächsten Versuch. Nach insgesamt 6 Versuchen endet die Zustellung. Redirects folgen wir nicht. Protokolliere Auftrags-ID, Eventtyp und Zustellstatus, aber niemals das Signatur-Secret.
Bleibt ein Callback aus, gleiche deine bekannten IDs über den GET-Endpoint ab. Bewahre diese IDs schon seit dem Anlegen auf. So kannst du eine fehlende Benachrichtigung untersuchen, ohne die Aufnahme erneut transkribieren zu lassen.