Webhooks

Översikt

Vissa händelser i ElevenLabs kan konfigureras för att utlösa webhooks, så att externa applikationer och system kan ta emot och bearbeta händelserna när de inträffar. Händelsetyper som stöds just nu är:

Konfiguration

Webhooks kan skapas, inaktiveras och tas bort från sidan med allmänna inställningar. För användare i Workspaces är det bara arbetsyteadministratörer som kan konfigurera webhooks för arbetsytan.

Efter att den har skapats kan webhooken väljas för att lyssna efter händelser i produktinställningar, till exempel Agents Platform.

Webhooks kan inaktiveras från sidan med allmänna inställningar när som helst. Webhooks som upprepade gånger misslyckas inaktiveras automatiskt om det finns 10 eller fler misslyckanden i följd och den senaste lyckade leveransen var för mer än 7 dagar sedan, eller om webhooken aldrig har levererats. Automatiskt inaktiverade webhooks måste aktiveras igen på inställningssidan. Webhooks kan tas bort om de inte används av några produkter.

Försök igen

Återförsök för webhooks kan aktiveras per webhook för att automatiskt försöka leverera igen när en begäran misslyckas. Återförsök är inaktiverade som standard. Aktivera återförsök när du skapar eller uppdaterar en webhook via API:et eller i webhook-inställningarna.

Schema för återförsök

När ett leveransförsök misslyckas med ett fel som kan återförsökas försöker systemet igen upp till 5 gånger med ökande fördröjning mellan försöken:

En liten slumpmässig variation (upp till 10 % av fördröjningen) läggs till vid varje återförsök för att fördela belastningen och undvika problem med många samtidiga förfrågningar.

Fel som kan återförsökas

Alla fel utlöser inte ett återförsök. Endast följande fel betraktas som möjliga att försöka igen:

• 5xx-statuskoder (serverfel som 500, 502, 503, 504).
• 429 (för många förfrågningar).
• 408 (tidsgränsen för begäran överskreds).
• Anslutningsfel och tidsgränser för begäranden.

Begärandefel i intervallet 4xx (som 400, 401, 403, 404) försöks inte igen, eftersom de vanligtvis indikerar ett konfigurationsproblem som kräver manuell korrigering.

Kögränser per webhook

Varje webhook är begränsad till 100 väntande återförsöksjobb. Om en webhook samlar fler än 100 återförsök i kö tas ytterligare jobb bort tills befintliga återförsök har bearbetats. Detta förhindrar att en enda felkonfigurerad webhook använder för mycket resurser.

Ljudwebhooks har ytterligare två gränser. En ljudnyttolast som är större än 50 MiB levereras en gång och försöks inte igen, och återförsök för ljud i kö för en enskild webhook får totalt inte överstiga 400 MiB.

Beteende vid automatisk inaktivering

Systemet spårar på varandra följande leveransfel för varje webhook. En webhook inaktiveras automatiskt när båda följande villkor är uppfyllda:

• 10 eller fler leveransfel i följd har inträffat.
• Webhooken har aldrig levererats, eller så var den senaste lyckade leveransen för mer än 7 dagar sedan.

När en webhook inaktiveras automatiskt får arbetsyteadministratörer en e-postnotifiering. Webhooken måste aktiveras manuellt från inställningssidan innan den återupptar leveranser.

Integration

För att integrera med webhooks skapar du en slutpunktshanterare som tar emot data om webhook-händelser som POST-begäranden. Efter att signaturen har validerats bör hanteraren snabbt returnera HTTP 200 för att ange att mottagandet lyckades. Upprepade misslyckanden med att returnera ett lyckat svar kan leda till att webhooken inaktiveras automatiskt.

Nyttolasten vid återförsök är identisk med det ursprungliga leveransförsöket. Webhook-konsumenter kan inte avgöra om det är en första leverans eller ett återförsök enbart utifrån nyttolasten, så utforma din hanterare så att den är idempotent — att bearbeta samma händelse flera gånger ska ge samma resultat. Använd event_timestamp och händelsespecifika identifierare (som conversation_id) för att avdubbla händelser vid behov.

Fält på toppnivå

Exempel på webhook-nyttolast

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

Autentisering

Det är viktigt att mottagaren validerar alla inkommande webhooks. Webhooks har för närvarande stöd för autentisering via HMAC-signaturer. Konfigurera HMAC-autentisering genom att:

• Lagra den delade hemligheten som genereras när webhooken skapas på ett säkert sätt
• Verifiera headern ElevenLabs-Signature i din endpoint med hjälp av SDK:n

JavaScript-SDK:n exponerar constructEvent; Python-SDK:n exponerar construct_event med rawBody, sig_header och secret (dessa heter inte payload / signature i Python). Båda verifierar signaturen, validerar tidsstämpeln och tolkar JSON-payloaden.

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