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 configurare i webhook del workspace.

Dopo la creazione, il webhook può essere selezionato per ricevere eventi nelle impostazioni dei prodotti, come Agents Platform.

I webhook possono essere disabilitati in qualsiasi momento dalla pagina delle impostazioni generali. I webhook che falliscono ripetutamente vengono disabilitati automaticamente se si verificano 10 o più errori consecutivi e l’ultima consegna riuscita risale a più di 7 giorni fa, oppure se non è mai stata effettuata una consegna riuscita. I webhook disabilitati automaticamente devono essere riabilitati dalla pagina delle impostazioni. I webhook possono essere eliminati se non sono utilizzati da alcun prodotto.

Tentativi

I tentativi di nuovo invio dei webhook possono essere abilitati per ciascun webhook per ritentare automaticamente la consegna quando una richiesta non riesce. Per impostazione predefinita, i tentativi sono disabilitati. 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 a causa di un errore ritentabile, il sistema ritenta fino a 5 volte con ritardi crescenti tra i tentativi:

A ogni tentativo viene aggiunto un piccolo jitter 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 delle richieste nella gamma 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 job di ritentativo in attesa. Se un webhook accumula più di 100 tentativi in coda, gli ulteriori job vengono scartati finché non vengono elaborati i tentativi esistenti. Ciò impedisce 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 volta e non viene ritentato, e i tentativi audio in coda per un singolo webhook non possono superare complessivamente 400 MiB.

Comportamento di disabilitazione automatica

Il sistema monitora gli errori consecutivi di consegna per ogni webhook. Un webhook viene disabilitato automaticamente quando sono soddisfatte entrambe le seguenti condizioni:

• 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. Il webhook deve essere riabilitato manualmente dalla pagina delle impostazioni prima di riprendere la consegna.

Integrazione

Per integrarti con i webhook, crea un handler dell’endpoint per ricevere i dati degli eventi webhook come richieste POST. Dopo aver convalidato la firma, l’handler deve restituire tempestivamente HTTP 200 per indicare la ricezione riuscita. La mancata restituzione ripetuta di una risposta di successo può comportare la disabilitazione automatica del webhook.

Il payload del tentativo è identico a quello del tentativo di consegna originale. I consumer del webhook non possono distinguere tra una consegna iniziale e un tentativo dal solo payload, quindi progetta il tuo handler in modo che sia idempotente: elaborare lo stesso evento più volte dovrebbe produrre lo stesso risultato. Se necessario, usa event_timestamp e 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"}