Webhooks: HMAC-Signatur, Zustellversuche und Best Practices
So erhalten Sie das Ergebnis von Transkriptionen per Webhook: HMAC-SHA256-Signatur, X-VPT-Signature- und X-VPT-Event-Header, 6 Zustellversuche mit Backoff.
Statt die API wiederholt abzufragen, um zu sehen, ob die Transkription abgeschlossen ist, geben Sie bei der Anforderung eine webhook_url an. VoxScriber sendet dann einen POST an Ihren Server, sobald der Auftrag abgeschlossen ist – egal ob mit Erfolg oder Fehler. Das ist die empfohlene Integrationsmethode: Es werden weniger Anfragen benötigt und das Ergebnis kommt sofort an.
So funktioniert es
- Sie senden die Audiodatei mit einer
webhook_url(zwingendhttps). - Wenn die Verarbeitung abgeschlossen ist, senden wir einen POST an diese URL mit dem Ergebnis.
- Ihr Server antwortet mit einem
2xx-Status, um den Empfang zu bestätigen.
Jede Zustellung enthält zwei Identifikations-Header:
| Header | Inhalt |
|---|---|
X-VPT-Event | Der Ereignistyp (Abschluss, Fehler usw.) |
X-VPT-Signature | HMAC-SHA256-Signatur der Zustellung |
Überprüfen Sie die Signatur immer, bevor Sie dem Inhalt vertrauen: Berechnen Sie den HMAC-SHA256 des empfangenen Bodys und vergleichen Sie ihn mit dem Wert des Headers X-VPT-Signature. Anfragen ohne gültige Signatur müssen verworfen werden – jeder kann die URL Ihres Endpoints herausfinden.
Automatische Zustellversuche
Wenn Ihr Endpoint nicht erreichbar ist oder zu lange braucht, versuchen wir es erneut:
- Timeout pro Versuch: 15 Sekunden.
- Maximale Anzahl Versuche: 6.
- Wartezeit zwischen den Versuchen (Backoff): 5 min → 30 min → 2 h → 6 h → 24 h.
Alle Zustellungen werden auf unserer Seite gespeichert, sodass der Verlauf bei Verlust mit dem Support geprüft werden kann.
Antworten Sie sofort mit 200 auf den Webhook und verarbeiten Sie den Inhalt asynchron (Warteschlange, Job). Wenn Ihre Verarbeitung länger als 15 Sekunden dauert, gilt die Zustellung als fehlgeschlagen und wird erneut in die Warteschlange eingereiht – Sie könnten dasselbe Ereignis also zweimal erhalten. Behandeln Sie die Ereignisse idempotent.
Sie erhalten immer ein Endergebnis
Hängende Aufträge verschwinden nicht lautlos:
- Ein Auftrag in der Warteschlange, der länger als 10 Minuten hängt, wird automatisch erneut eingereiht.
- Ein Auftrag in Verarbeitung, der länger als 60 Minuten hängt, wird als fehlgeschlagen markiert – und löst einen Fehler-Webhook an Ihre URL aus.
Das bedeutet: Für jede gesendete Audiodatei erhält Ihr System einen abschließenden Callback, ob Erfolg oder Fehler.
FAQ
Mein Server war offline. Habe ich das Ergebnis verloren?
Wahrscheinlich nicht: Es gibt bis zu 6 Versuche über etwa 24 Stunden. Wenn alle fehlschlagen, wird der Zustellverlauf gespeichert – wenden Sie sich an den Support, um die Zustellung erneut auszulösen.
Kann ich eine http-URL (ohne TLS) verwenden?
Nein. Aus Sicherheitsgründen akzeptieren wir nur https-URLs, ohne Weiterleitungen, und interne/private Adressen sind blockiert.
Wie unterscheide ich einen Erfolg- von einem Fehler-Webhook?
Über den Header X-VPT-Event, der den Ereignistyp identifiziert, und den Inhalt der Zustellung.
Wie muss mein Endpoint antworten?
Mit einem beliebigen 2xx-Status innerhalb von 15 Sekunden. Andere Status (oder Timeout) gelten als Fehlschlag und führen zu einer erneuten Zustellung.
Verwandte Artikel
Nicht weitergeholfen? Öffnen Sie ein Ticket – unser Team antwortet schnell.