Asynchrones Speech to Text
In diesem Leitfaden erfahren Sie, wie Sie Webhooks für asynchrone Benachrichtigungen nach Abschluss von Transkriptionsaufgaben verwenden.
Anleitung · Setzt voraus, dass Sie den Speech to Text- Schnellstart abgeschlossen haben.
Überblick
Mit Webhooks erhalten Sie automatisch Benachrichtigungen, wenn Ihre Speech-to-Text-Transkriptionsaufgaben abgeschlossen sind. So müssen Sie die API nicht kontinuierlich auf Statusupdates abfragen. Das ist besonders nützlich für lang laufende Transkriptionsaufträge oder bei der Verarbeitung großer Mengen an Audiodateien.
Wenn eine Transkription abgeschlossen ist, sendet ElevenLabs eine POST-Anfrage an Ihre angegebene Webhook-URL mit den Transkriptionsergebnissen, einschließlich Transkripttext, Spracherkennung und Metadaten.
Webhooks verwenden
Diese Anleitung setzt voraus, dass Sie Ihren API-Schlüssel und das SDK eingerichtet haben. Schließen Sie zuerst den Schnellstart ab, falls Sie dies noch nicht getan haben.
Webhook erstellen oder bearbeiten
Gehen Sie im ElevenLabs-Dashboard zu Entwickler > Webhooks. Klicken Sie auf Webhook erstellen oder bearbeiten Sie einen vorhandenen Webhook.

Konfigurieren Sie den Webhook mit:
- Name: Ein aussagekräftiger Name für Ihren Webhook
- Callback-URL: Ihr öffentlich zugänglicher HTTPS-Endpunkt
- Webhook-Authentifizierungsmethode: Entweder
HMACoderOAuth. Der Client implementiert den Verifizierungsmechanismus. ElevenLabs sendet Header, die eine Verifizierung ermöglichen, erzwingt sie aber nicht. - Ereignisse: Wählen Sie Transkription abgeschlossen.
Webhook-Payload
Wenn eine Transkription abgeschlossen ist, erhält Ihr Webhook-Endpunkt eine POST-Anfrage mit den Transkriptions- und Webhook-Daten:
Details zur Struktur der Antwort finden Sie in der Referenz zur Speech-to-Text-API.
Falls die Anfrage eine transcript_edit-Anweisung enthielt, enthält das transcription-Objekt außerdem ein Feld edited_transcript mit dem bearbeiteten Text.
Falls die Transkription fehlschlägt, erhält Ihr Endpunkt stattdessen ein webhook_error-Ereignis. Es hat kein data-Objekt: Es enthält eine request_id auf oberster Ebene (dieselbe ID, die bei Annahme der Anfrage zurückgegeben wurde), eine error_message und die webhook_metadata der Anfrage.
Ihren Webhook-Endpunkt implementieren
Hier ist ein Beispiel für die Implementierung eines Webhook-Endpunkts zur Verarbeitung eingehender Benachrichtigungen:
Sicherheitsaspekte
Signaturprüfung
Prüfen Sie immer Webhook-Signaturen, um sicherzustellen, dass Anfragen von ElevenLabs stammen.
HTTPS-Anforderung
Webhook-URLs müssen HTTPS verwenden, um die sichere Übertragung von Transkriptionsdaten zu gewährleisten.
Ratenbegrenzung
Implementieren Sie eine Ratenbegrenzung an Ihrem Webhook-Endpunkt, um Missbrauch zu verhindern:
Fehlerantworten
Geben Sie einen 2xx-Statuscode zurück, um den Webhook zu bestätigen.
Standardmäßig werden Speech-to-Text-Transkriptionswebhooks einmal zugestellt. Jede Nicht-2xx-Antwort zählt als fehlgeschlagene Zustellung, und wiederholte Fehler deaktivieren den Webhook automatisch.
Wenn Sie Wiederholungsversuche für den Webhook aktivieren, werden fehlgeschlagene Zustellungen (5xx, 408, 429 oder Verbindungsfehler) bis zu fünf weitere Male wiederholt: ungefähr 30 Sekunden, 2 Minuten, 8 Minuten, 30 Minuten und 30 Minuten nach dem vorherigen Versuch. Andere 4xx-Antworten werden nicht wiederholt. Jeder Versuch für dasselbe Ereignis enthält denselben Header ElevenLabs-Webhook-Delivery-Id, sodass Ihr Handler Duplikate ignorieren kann.
Anfragen mit enable_logging auf false (Modus ohne Speicherung) erhalten bei aktivierten Wiederholungsversuchen bis zu zwei schnelle Wiederholungen, 5 Sekunden und 30 Sekunden nach dem vorherigen Versuch. Das Transkript wird niemals gespeichert.
Falls eine Zustellung weiterhin fehlschlägt, rufen Sie das Ergebnis mit Transkript abrufen über die transcription_id ab, die bei Annahme der Anfrage zurückgegeben wurde. Transkripte werden für Anfragen mit enable_logging auf false nicht gespeichert.
Webhooks testen
Lokale Entwicklung
Verwenden Sie für lokale Tests Tools wie ngrok, um Ihren lokalen Server verfügbar zu machen:
Verwenden Sie während der Entwicklung die bereitgestellte HTTPS-URL als Ihren Webhook-Endpunkt.
Webhook-Tests
Sie können Ihre Webhook-Implementierung testen, indem Sie eine Transkriptionsanfrage stellen und Ihren Endpunkt überwachen: