# Den Abschluss einer Transkription per Webhook empfangen

> Lass dir den Status deiner Transkription per Webhook melden: signierter POST an deine webhook_url bei Abschluss oder Fehler, ohne laufende Statusabfragen.

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

Lass dir den Status deiner Transkription per Webhook melden, indem du beim Anlegen webhook_url mitsendest. Wir schicken einen signierten POST, sobald der Auftrag abgeschlossen ist oder fehlschlägt. Deine Anwendung kann auf das Event warten, statt laufend den Status abzufragen.

- transcription.completed und transcription.failed
- Jede Zustellung mit HMAC-SHA256 signiert
- Bis zu 6 Zustellversuche mit wachsenden Abständen

## Event annehmen, dann das Transkript abrufen

### Abschluss und Fehler getrennt behandeln

Du bekommst transcription.completed oder transcription.failed. Wenn du eine Transkription abbrichst, senden wir keinen Webhook.

### Signatur mit deinem Team-Secret prüfen

X-Transcript1-Signature enthält einen Zeitstempel und die HMAC-SHA256-Signatur des unveränderten Bodys. Als Schlüssel dient das whsec_-Secret deines Teams.

### Bei fehlender Bestätigung erneut zustellen

Jede 2xx-Antwort bestätigt die Zustellung. Sonst versuchen wir es nach 2, 4, 8, 16 und 32 Minuten erneut. Insgesamt gibt es bis zu 6 Versuche.

### Nur öffentliche HTTPS-Adressen

Die URL muss HTTPS nutzen und auf eine öffentliche Adresse zeigen. Wir prüfen sie beim Anlegen der Transkription und bei jedem Zustellversuch.

### Das Event enthält nicht den fertigen Text

Im Event steht das Transkriptionsobjekt ohne Transkript. Rufe den fertigen Text anschließend über die ID im gewünschten Format ab.

## 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](https://transcript1.com/de/docs/webhooks#set-a-webhook-url) 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.

### Upload mit Webhook anlegen

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

## Schnell 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](https://transcript1.com/de/docs/api-reference#get-a-transcription).

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.

### POST an deinen Endpoint

```
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](https://transcript1.com/de/docs/webhooks#verify-the-signature) 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.

### 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));
```

- [Vollständige Beispiele zur Signaturprüfung](https://transcript1.com/de/docs/webhooks)

## 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](https://transcript1.com/de/docs/api-reference#get-a-transcription) ab. Bewahre diese IDs schon seit dem Anlegen auf. So kannst du eine fehlende Benachrichtigung untersuchen, ohne die Aufnahme erneut transkribieren zu lassen.

## Häufige Fragen

### Wo finde ich das Signatur-Secret?

Im Dashboard unter „Webhooks“. Das Secret beginnt mit whsec_ und gehört deinem Team. Du kannst es dort jederzeit rotieren.

### Was passiert, wenn mein Endpoint nicht antwortet?

Wir wiederholen die Zustellung mit wachsenden Abständen, insgesamt bis zu 6-mal über etwa eine Stunde. Jeder Versuch hat ein Timeout von 10 Sekunden. Weiterleitungen folgen wir nicht.

### Kann ich Webhooks auch über MCP einrichten?

Nein. Webhooks gibt es nur in der REST API. Die MCP-Tools warten auf das Transkript oder geben eine ID zurück, mit der der Assistent später weiterlesen kann.

## Passend dazu

- [Webhooks einrichten (Doku)](https://transcript1.com/de/docs/webhooks)
- [Audio- und Video-API](https://transcript1.com/de/features/speech-to-text-api)
- [KI-Agenten und LLMs](https://transcript1.com/de/use-cases/transkripte-fuer-ki-agenten)