Webhook

Panoramica

Puoi configurare determinati eventi in ElevenLabs affinché attivino webhook, consentendo ad applicazioni e sistemi esterni di ricevere ed elaborare questi eventi quando si verificano. I tipi di evento attualmente supportati includono:

Configurazione

I webhook possono essere creati, disabilitati ed eliminati dalla pagina delle impostazioni generali. Per gli utenti nei workspace, solo gli amministratori del workspace possono configurarne i webhook.

Dopo la creazione, il webhook può essere selezionato per ascoltare gli eventi nelle impostazioni del prodotto, ad esempio in Agents Platform.

Gli eventi flows_generation e flows_template_run sono entrambi abilitati da un’unica sottoscrizione: in Select events to listen to, seleziona Image & Video API generation or template run completed, oppure passa l’evento flows a Update workspace webhook. Una generazione o un’esecuzione invia il proprio evento solo se la 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 se si verificano 10 o più errori consecutivi e l’ultima consegna riuscita risale a più di 7 giorni prima oppure non è mai avvenuta. I webhook disabilitati automaticamente devono essere riabilitati dalla pagina delle impostazioni. Puoi eliminare i webhook se non sono utilizzati da alcun prodotto.

Tentativi

Puoi abilitare i tentativi per ciascun webhook, affinché la consegna venga ritentata automaticamente quando una richiesta non riesce. I tentativi sono disabilitati per impostazione predefinita. Abilitali quando crei o aggiorni un webhook tramite l’API o nelle impostazioni del webhook.

Pianificazione dei 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 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. Sono considerati ritentabili solo i seguenti errori:

• 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 di richiesta 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 ritentativo in attesa. Se un webhook accumula più di 100 tentativi in coda, i processi aggiuntivi vengono ignorati finché non vengono elaborati quelli esistenti. Questo evita che un singolo webhook configurato in modo errato consumi risorse eccessive.

I webhook audio hanno due limiti aggiuntivi. Un payload audio superiore a 50 MiB viene consegnato una sola volta e non viene ritentato; inoltre, i tentativi audio in coda per un singolo webhook non possono superare complessivamente 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 prima.

Quando un webhook viene disabilitato automaticamente, gli amministratori del workspace ricevono una notifica email. Il webhook deve essere riabilitato manualmente dalla pagina delle impostazioni prima di riprendere le consegne.

Integrazione

Per integrare i webhook, crea un gestore di endpoint che riceva i dati degli eventi webhook come richieste POST. Dopo aver convalidato la firma, il gestore deve restituire prontamente HTTP 200 per indicare che la ricezione è avvenuta con successo. Il mancato invio ripetuto di una risposta di successo può portare alla disabilitazione automatica del webhook.

Il payload del tentativo è identico a quello del tentativo di consegna originale. I consumer di webhook non possono distinguere tra una consegna iniziale e un tentativo basandosi solo sul payload, quindi progetta il tuo gestore affinché sia idempotente: elaborare più volte lo stesso evento deve produrre lo stesso risultato. Se necessario, usa event_timestamp e gli identificatori specifici dell’evento, come conversation_id, per deduplicare gli eventi.

Campi di primo livello

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"
      }
    }
  }
}

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.

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"}