Webhooks

Übersicht

Bestimmte Ereignisse in ElevenLabs können Webhooks auslösen, sodass externe Anwendungen und Systeme diese Ereignisse bei ihrem Auftreten empfangen und verarbeiten können. Derzeit werden folgende Ereignistypen unterstützt:

Konfiguration

Webhooks können auf der Seite mit den allgemeinen Einstellungen erstellt, deaktiviert und gelöscht werden. Für Nutzer in Workspaces können nur Workspace-Admins die Webhooks für den Workspace konfigurieren.

Nach der Erstellung kann der Webhook ausgewählt werden, um in Produkteinstellungen wie Agents Platform auf Ereignisse zu warten.

Webhooks können jederzeit auf der Seite mit den allgemeinen Einstellungen deaktiviert werden. Webhooks, die wiederholt fehlschlagen, werden automatisch deaktiviert, wenn mindestens 10 aufeinanderfolgende Fehler auftreten und die letzte erfolgreiche Zustellung mehr als 7 Tage zurückliegt oder noch nie eine erfolgreiche Zustellung erfolgt ist. Automatisch deaktivierte Webhooks müssen auf der Einstellungsseite erneut aktiviert werden. Webhooks können gelöscht werden, wenn sie von keinem Produkt verwendet werden.

Wiederholungsversuche

Wiederholungsversuche für Webhooks können pro Webhook aktiviert werden, um die Zustellung bei fehlgeschlagenen Anfragen automatisch erneut zu versuchen. Wiederholungsversuche sind standardmäßig deaktiviert. Aktivieren Sie sie beim Erstellen oder Aktualisieren eines Webhooks über die API oder in den Webhook-Einstellungen.

Zeitplan für Wiederholungsversuche

Wenn ein Zustellversuch mit einem wiederholbaren Fehler fehlschlägt, versucht das System die Zustellung bis zu 5-mal mit zunehmenden Verzögerungen:

Jedem Wiederholungsversuch wird ein kleiner zufälliger Jitter hinzugefügt (bis zu 10 % der Verzögerung), um die Last zu verteilen und Thundering-Herd-Probleme zu vermeiden.

Wiederholbare Fehler

Nicht jeder Fehler löst einen Wiederholungsversuch aus. Nur die folgenden HTTP-Statuscodes gelten als wiederholbar:

• 5xx-Statuscodes (Serverfehler wie 500, 502, 503, 504).
• 429 (Zu viele Anfragen).
• 408 (Zeitüberschreitung der Anfrage).

Anfragefehler im Bereich 4xx (wie 400, 401, 403, 404) werden nicht wiederholt, da sie in der Regel auf ein Konfigurationsproblem hinweisen, das manuell behoben werden muss.

Warteschlangenlimits pro Webhook

Jeder Webhook ist auf 100 ausstehende Wiederholungsjobs begrenzt. Sammelt ein Webhook mehr als 100 Wiederholungsversuche in der Warteschlange an, werden zusätzliche Jobs verworfen, bis vorhandene Wiederholungsversuche verarbeitet sind. Dadurch kann ein einzelner falsch konfigurierter Webhook nicht übermäßig viele Ressourcen verbrauchen.

Verhalten bei automatischer Deaktivierung

Das System verfolgt für jeden Webhook aufeinanderfolgende Zustellfehler. Ein Webhook wird automatisch deaktiviert, wenn beide folgenden Bedingungen erfüllt sind:

• Es sind mindestens 10 aufeinanderfolgende Zustellfehler aufgetreten.
• Der Webhook wurde noch nie erfolgreich zugestellt oder die letzte erfolgreiche Zustellung liegt mehr als 7 Tage zurück.

Wenn ein Webhook automatisch deaktiviert wird, erhalten Workspace-Admins eine E-Mail-Benachrichtigung. Der Webhook muss auf der Einstellungsseite manuell erneut aktiviert werden, bevor er wieder Zustellungen durchführt.

Integration

Erstellen Sie für die Integration mit Webhooks einen Endpoint-Handler, der Webhook-Ereignisdaten als POST-Anfragen empfängt. Nach der Validierung der Signatur sollte der Handler umgehend HTTP 200 zurückgeben, um den erfolgreichen Empfang zu bestätigen. Wenn wiederholt keine erfolgreiche Antwort zurückgegeben wird, kann der Webhook automatisch deaktiviert werden.

Die Nutzlast bei Wiederholungsversuchen ist mit der des ursprünglichen Zustellversuchs identisch. Webhook-Clients können allein anhand der Nutzlast nicht zwischen einer erstmaligen Zustellung und einem Wiederholungsversuch unterscheiden. Gestalten Sie Ihren Handler daher idempotent — die mehrfache Verarbeitung desselben Ereignisses sollte zum gleichen Ergebnis führen. Verwenden Sie bei Bedarf event_timestamp und ereignisspezifische Kennungen (wie conversation_id), um Ereignisse zu deduplizieren.

Felder der obersten Ebene

Beispiel für eine Webhook-Nutzlast

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

Authentifizierung

Der Listener muss alle eingehenden Webhooks validieren. Webhooks unterstützen derzeit die Authentifizierung über HMAC-Signaturen. So richten Sie die HMAC-Authentifizierung ein:

• Speichern Sie das beim Erstellen des Webhooks generierte gemeinsame Geheimnis sicher.
• Verifizieren Sie den Header ElevenLabs-Signature in Ihrem Endpunkt mithilfe des SDK.

Das JavaScript-SDK stellt constructEvent bereit, das Python-SDK construct_event mit rawBody, sig_header und secret (diese heißen in Python nicht payload / signature). Beide verifizieren die Signatur, validieren den Zeitstempel und parsen die JSON-Nutzlast.

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