Vai alla navigazione

Webhook

Abilita integrazioni esterne ricevendo eventi 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:

Tipo di eventoDescrizione
post_call_transcriptionUna chiamata della piattaforma Agents è terminata e l’analisi è completa
voice_removal_noticeÈ pianificata la rimozione di una voce condivisa
voice_removal_notice_withdrawnLa rimozione di una voce condivisa non è più pianificata
voice_removedUna voce condivisa è stata rimossa e non è più utilizzabile
flows_generationUna generazione di Immagini e Video è stata completata o non è riuscita
flows_template_runL’esecuzione di un template è stata completata o non è riuscita

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.

Configurazione del webhook HMAC

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:

TentativoRitardo
1Immediato
230 secondi
32 minuti
48 minuti
530 minuti

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

CampoTipoDescrizione
typestringTipo di evento
dataobjectDati dell’evento
event_timestampnumberData e ora dell’evento in formato unix UTC

Esempio di payload webhook

{
"type": "post_call_transcription",
"event_timestamp": 1739537297,
"data": {
"agent_id": "xyz",
"conversation_id": "abc",
"status": "done",
"transcript": [
{
"role": "agent",
"message": "Hey there angelo. How are you?",
"tool_calls": null,
"tool_results": null,
"feedback": null,
"time_in_call_secs": 0,
"conversation_turn_metrics": null
},
{
"role": "user",
"message": "Hey, can you tell me, like, a fun fact about 11 Labs?",
"tool_calls": null,
"tool_results": null,
"feedback": null,
"time_in_call_secs": 2,
"conversation_turn_metrics": null
},
{
"role": "agent",
"message": "I do not have access to fun facts about Eleven Labs. However, I can share some general information about the company. Eleven Labs is an AI voice technology platform that specializes in voice cloning and text-to-speech...",
"tool_calls": null,
"tool_results": null,
"feedback": null,
"time_in_call_secs": 9,
"conversation_turn_metrics": {
"convai_llm_service_ttfb": {
"elapsed_time": 0.3704247010173276
},
"convai_llm_service_ttf_sentence": {
"elapsed_time": 0.5551181449554861
}
}
}
],
"metadata": {
"start_time_unix_secs": 1739537297,
"call_duration_secs": 22,
"cost": 296,
"deletion_settings": {
"deletion_time_unix_secs": 1802609320,
"deleted_logs_at_time_unix_secs": null,
"deleted_audio_at_time_unix_secs": null,
"deleted_transcript_at_time_unix_secs": null,
"delete_transcript_and_pii": true,
"delete_audio": true
},
"feedback": {
"overall_score": null,
"likes": 0,
"dislikes": 0
},
"authorization_method": "authorization_header",
"charging": {
"dev_discount": true
},
"termination_reason": ""
},
"analysis": {
"evaluation_criteria_results": {},
"data_collection_results": {},
"call_successful": "success",
"transcript_summary": "The conversation begins with the agent asking how Angelo is, but Angelo redirects the conversation by requesting a fun fact about 11 Labs. The agent acknowledges they don't have specific fun facts about Eleven Labs but offers to provide general information about the company. They briefly describe Eleven Labs as an AI voice technology platform specializing in voice cloning and text-to-speech technology. The conversation is brief and informational, with the agent adapting to the user's request despite not having the exact information asked for."
},
"conversation_initiation_client_data": {
"conversation_config_override": {
"agent": {
"prompt": null,
"first_message": null,
"language": "en"
},
"tts": {
"voice_id": null
}
},
"custom_llm_extra_body": {},
"dynamic_variables": {
"user_name": "angelo"
}
}
}
}

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

CampoTipoDescrizione
voice_idstringL’ID della voce la cui rimozione è pianificata
future_removal_timestampnumberQuando la voce non sarà più utilizzabile, in formato unix UTC
suggested_voicesarrayFino a 3 voci simili. Vedi Voci suggerite
{
"type": "voice_removal_notice",
"event_timestamp": 1739537297,
"data": {
"voice_id": "21m00Tcm4TlvDq8ikWAM",
"future_removal_timestamp": 1742129297,
"suggested_voices": [
["https://elevenlabs.io/app/voice-lab/share/a1b2c3d4e5f6/EXAVITQu4vr4xnSDxMaL", "Sarah"]
]
}
}

Avviso di rimozione ritirato (voice_removal_notice_withdrawn)

La rimozione della voce non è più pianificata e rimane utilizzabile.

Struttura dell’oggetto dati

CampoTipoDescrizione
voice_idstringL’ID della voce che non verrà più rimossa
{
"type": "voice_removal_notice_withdrawn",
"event_timestamp": 1739537297,
"data": {
"voice_id": "21m00Tcm4TlvDq8ikWAM"
}
}

Voce rimossa (voice_removed)

La voce è stata rimossa senza un periodo di preavviso e non è più utilizzabile.

Struttura dell’oggetto dati

CampoTipoDescrizione
voice_idstringL’ID della voce rimossa
suggested_voicesarrayFino a 3 voci simili. Vedi Voci suggerite
{
"type": "voice_removed",
"event_timestamp": 1739537297,
"data": {
"voice_id": "21m00Tcm4TlvDq8ikWAM",
"suggested_voices": [
["https://elevenlabs.io/app/voice-lab/share/a1b2c3d4e5f6/EXAVITQu4vr4xnSDxMaL", "Sarah"]
]
}
}

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.

Esempio di gestore webhook con FastAPI:

from dotenv import load_dotenv
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from elevenlabs.client import ElevenLabs
from elevenlabs.errors import BadRequestError
import os
load_dotenv()
app = FastAPI()
elevenlabs = ElevenLabs(
api_key=os.getenv("ELEVENLABS_API_KEY"),
)
WEBHOOK_SECRET = os.getenv("WEBHOOK_SECRET")
@app.post("/webhook")
async def receive_message(request: Request):
payload = await request.body()
signature = request.headers.get("elevenlabs-signature")
try:
event = elevenlabs.webhooks.construct_event(
rawBody=payload.decode("utf-8"),
sig_header=signature,
secret=WEBHOOK_SECRET,
)
except BadRequestError as e:
return JSONResponse(content={"error": "Invalid signature"}, status_code=401)
# construct_event returns a dict (parsed JSON), not an object with attributes
if event.get("type") == "post_call_transcription":
print(f"Received transcription: {event.get('data')}")
return {"status": "received"}