Speech to Text asincrono
Questa guida mostra come usare i webhook per ricevere notifiche asincrone al completamento delle attività di trascrizione.
Guida pratica · Presuppone che tu abbia completato la guida rapida di Speech to Text .
Panoramica
I webhook ti consentono di ricevere notifiche automatiche al completamento delle attività di trascrizione Speech to Text, eliminando la necessità di interrogare continuamente l’API per gli aggiornamenti di stato. Sono particolarmente utili per lavori di trascrizione di lunga durata o quando elabori grandi volumi di file audio.
Quando una trascrizione è completata, ElevenLabs invierà una richiesta POST all’URL webhook specificato con i risultati della trascrizione, inclusi il testo trascritto, il rilevamento della lingua ed eventuali metadati.
Utilizzare i webhook
Questa guida presuppone che tu abbia configurato la chiave API e l’SDK. Completa prima la guida rapida, se non l’hai ancora fatto.
Crea o modifica un webhook
Nella dashboard di ElevenLabs, vai a Sviluppatori > Webhook. Fai clic su Crea webhook oppure modifica un webhook esistente.

Configura il webhook con:
- Nome: un nome descrittivo per il webhook
- URL di callback: il tuo endpoint HTTPS accessibile pubblicamente
- Metodo di autenticazione del webhook:
HMACoOAuth. Spetta al client implementare il meccanismo di verifica. ElevenLabs invia header che consentono la verifica, ma non la imponiamo. - Eventi: seleziona Trascrizione completata.
Payload del webhook
Quando una trascrizione è completata, l’endpoint webhook riceverà una richiesta POST con i dati della trascrizione e del webhook:
Consulta il riferimento dell’API Speech-to-Text per conoscere i dettagli della struttura della risposta.
Se la richiesta includeva un’istruzione transcript_edit, l’oggetto transcription contiene anche un campo edited_transcript con il testo modificato.
Se la trascrizione non riesce, l’endpoint riceve invece un evento webhook_error. Non ha un oggetto data: include un request_id di primo livello (lo stesso ID restituito quando la richiesta è stata accettata), un error_message e il webhook_metadata della richiesta.
Implementare l’endpoint webhook
Ecco un esempio di come implementare un endpoint webhook per gestire le notifiche in arrivo:
Considerazioni sulla sicurezza
Verifica della firma
Verifica sempre le firme dei webhook per assicurarti che le richieste provengano da ElevenLabs.
Requisito HTTPS
Gli URL webhook devono utilizzare HTTPS per garantire la trasmissione sicura dei dati di trascrizione.
Limitazione della frequenza
Implementa la limitazione della frequenza sull’endpoint webhook per prevenire abusi:
Risposte in caso di errore
Restituisci un codice di stato 2xx per confermare il webhook.
Per impostazione predefinita, i webhook di trascrizione Speech to Text vengono inviati una sola volta. Ogni risposta non 2xx conta come consegna non riuscita e gli errori ripetuti disabilitano automaticamente il webhook.
Se attivi i tentativi per il webhook, le consegne non riuscite (5xx, 408, 429 o errori di connessione) vengono ritentate fino a 5 volte, approssimativamente 30 secondi, 2 minuti, 8 minuti, 30 minuti e 30 minuti dopo il tentativo precedente. Le altre risposte 4xx non vengono ritentate. Ogni tentativo per lo stesso evento include lo stesso header ElevenLabs-Webhook-Delivery-Id, quindi il tuo handler può ignorare i duplicati.
Le richieste effettuate con enable_logging impostato su false (modalità di conservazione zero) ricevono fino a 2 tentativi rapidi, 5 secondi e 30 secondi dopo il tentativo precedente, quando i tentativi sono attivati. La trascrizione non viene mai memorizzata.
Se una consegna continua a non riuscire, recupera il risultato con Ottieni trascrizione utilizzando il transcription_id restituito quando la richiesta è stata accettata. Le trascrizioni non vengono memorizzate per le richieste effettuate con enable_logging impostato su false.
Testare i webhook
Sviluppo locale
Per i test locali, usa strumenti come ngrok per esporre il tuo server locale:
Durante lo sviluppo, usa l’URL HTTPS fornito come endpoint webhook.
Test del webhook
Puoi testare l’implementazione del webhook effettuando una richiesta di trascrizione e monitorando l’endpoint: