Webhook
Panoramica
Puoi configurare alcuni eventi all’interno di ElevenLabs affinché attivino webhook, consentendo ad applicazioni e sistemi esterni di ricevere ed elaborare questi eventi mentre si verificano. I tipi di eventi attualmente supportati includono:
Configurazione
Puoi creare, disabilitare ed eliminare i webhook dalla pagina delle impostazioni generali. Per gli utenti nei workspace, solo gli amministratori del workspace possono configurarne i webhook.

Dopo la creazione, puoi selezionare il webhook per ascoltare gli eventi nelle impostazioni del prodotto, ad esempio nella piattaforma Agents.
Gli eventi flows_generation e flows_template_run vengono entrambi abilitati da un’unica sottoscrizione: in Seleziona gli eventi da ascoltare, seleziona Generazione API di Immagini e Video o esecuzione di template completata, oppure passa l’evento flows a Aggiorna webhook del workspace. Una generazione o un’esecuzione invia il proprio evento solo quando la relativa richiesta di creazione include un campo webhook.
Puoi disabilitare i webhook dalla pagina delle impostazioni generali in qualsiasi momento. I webhook che non riescono ripetutamente vengono disabilitati automaticamente in presenza di 10 o più errori consecutivi e se l’ultima consegna riuscita risale a più di 7 giorni fa o non è mai avvenuta. I webhook disabilitati automaticamente devono essere riattivati dalla pagina delle impostazioni. Puoi eliminare i webhook se non sono usati da alcun prodotto.
Nuovi tentativi
Puoi abilitare i nuovi tentativi per ogni webhook affinché la consegna venga ritentata automaticamente quando una richiesta non riesce. Per impostazione predefinita, i nuovi tentativi sono disabilitati. Abilitali quando crei o aggiorni un webhook tramite l’API o nelle impostazioni del webhook.
I nuovi tentativi sono supportati per i webhook post-chiamata
di ElevenAgents, inclusi gli eventi di trascrizione
(post_call_transcription), audio (post_call_audio) e di mancato avvio della chiamata
(call_initiation_failure).
Pianificazione dei nuovi tentativi
Quando un tentativo di consegna non riesce con un errore ritentabile, il sistema ritenta fino a 5 volte con ritardi crescenti tra un tentativo e l’altro:
A ogni nuovo tentativo viene aggiunta una piccola variazione casuale (fino al 10% del ritardo) per distribuire il carico ed evitare problemi di thundering herd.
Errori ritentabili
Non tutti gli errori attivano un nuovo tentativo. Solo i seguenti errori sono considerati ritentabili:
- Codici di stato
5xx(errori del server come 500, 502, 503, 504). 429(Troppe richieste).408(Timeout della richiesta).- Errori di connessione e timeout delle richieste.
Gli errori delle richieste nell’intervallo 4xx (come 400, 401, 403, 404) non vengono ritentati, poiché in genere indicano un problema di configurazione che richiede una correzione manuale.
Limiti della coda per webhook
Ogni webhook è limitato a 100 processi di nuovo tentativo in attesa. Se un webhook accumula più di 100 nuovi tentativi in coda, i processi aggiuntivi vengono eliminati finché non vengono elaborati quelli esistenti. Ciò impedisce a un singolo webhook configurato in modo errato di consumare risorse eccessive.
I webhook audio hanno due limiti aggiuntivi. Un payload audio superiore a 50 MiB viene consegnato una volta e non viene ritentato, e il totale dei nuovi tentativi audio in coda per un singolo webhook non può superare 400 MiB.
Comportamento di disabilitazione automatica
Il sistema tiene traccia degli errori consecutivi di consegna per ogni webhook. Un webhook viene disabilitato automaticamente quando sono soddisfatte entrambe le condizioni seguenti:
- Si sono verificati 10 o più errori consecutivi di consegna.
- Il webhook non è mai stato consegnato correttamente oppure l’ultima consegna riuscita risale a più di 7 giorni fa.
Quando un webhook viene disabilitato automaticamente, gli amministratori del workspace ricevono una notifica via email. Devi riabilitare manualmente il webhook dalla pagina delle impostazioni prima che riprenda le consegne.
Integrazione
Per integrare i webhook, crea un handler dell’endpoint che riceva i dati degli eventi webhook come richieste POST. Dopo aver convalidato la firma, l’handler deve restituire tempestivamente HTTP 200 per indicare che la ricezione è avvenuta correttamente. Il mancato invio ripetuto di una risposta di successo può comportare la disabilitazione automatica del webhook.
Il payload del nuovo tentativo è identico a quello del tentativo di consegna originale. I consumer dei webhook non possono distinguere un invio iniziale da un nuovo tentativo basandosi soltanto sul payload, quindi progetta il tuo handler in modo che sia idempotente: l’elaborazione dello stesso evento più volte deve produrre lo stesso risultato. Se necessario, usa event_timestamp e gli identificatori specifici dell’evento (come conversation_id) per eliminare i duplicati.
Campi di primo livello
Esempio di payload webhook
Webhook di rimozione delle voci
Un workspace riceve questi eventi per una voce condivisa della Voice Library che ha aggiunto, quando il proprietario della voce o ElevenLabs la rimuove dalla Voice Library.
Avviso di rimozione (voice_removal_notice)
La voce ha un periodo di preavviso. Rimane utilizzabile fino a future_removal_timestamp.
Non viene inviato alcun altro evento quando il periodo di preavviso termina.
Struttura dell’oggetto dati
Avviso di rimozione ritirato (voice_removal_notice_withdrawn)
La rimozione della voce non è più pianificata e rimane utilizzabile.
Struttura dell’oggetto dati
Voce rimossa (voice_removed)
La voce è stata rimossa senza un periodo di preavviso e non è più utilizzabile.
Struttura dell’oggetto dati
Voci suggerite
Ogni elemento in suggested_voices è un array di due elementi: l’URL di condivisione della voce nella Voice Library, seguito dal nome della voce. L’elenco può essere vuoto.
Autenticazione
È importante che il listener convalidi tutti i webhook in arrivo. I webhook supportano attualmente l’autenticazione tramite firme HMAC. Configura l’autenticazione HMAC:
- Archiviando in modo sicuro il segreto condiviso generato alla creazione del webhook
- Verificando l’header ElevenLabs-Signature nel tuo endpoint tramite l’SDK
L’SDK JavaScript espone constructEvent; l’SDK Python espone construct_event con rawBody, sig_header e secret (in Python non si chiamano payload / signature). Entrambi verificano la firma, convalidano il timestamp e analizzano il payload JSON.
Python
JavaScript
Esempio di gestore webhook con FastAPI: