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 behandla dessa händelser när de inträffar. Händelsetyper som för närvarande stöds är:

Konfiguration

Webhooks kan skapas, inaktiveras och tas bort på sidan för allmänna inställningar. För användare i arbetsytor kan endast arbetsytans administratörer konfigurera arbetsytans webhooks.

När webhooken har skapats kan den väljas för att lyssna på händelser i produktinställningar som Agents Platform.

Händelserna flows_generation och flows_template_run aktiveras båda av en prenumeration: under Select events to listen to markerar du Image & Video API generation or template run completed, eller skickar händelsen flows till Update workspace webhook. En generering eller körning skickar endast sin händelse när dess skapandebegäran innehåller ett webhook-fält.

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

Återförsök

Återförsök för webhookar 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:t eller i webhook-inställningarna.

Schema för återförsök

När ett leveransförsök misslyckas med ett fel som kan försökas igen, försöker systemet upp till 5 gånger med ökande fördröjningar 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örsök.

Fel som kan försökas igen

Alla misslyckanden utlöser inte ett återförsök. Endast följande misslyckanden anses kunna försökas igen:

• Statuskoderna 5xx (serverfel som 500, 502, 503, 504).
• 429 (för många begäranden).
• 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.

Gränser för köer per webhook

Varje webhook är begränsad till 100 väntande återförsöksjobb. Om en webhook samlar på sig fler än 100 återförsök i kö tas ytterligare jobb bort tills befintliga återförsök har behandlats. Det förhindrar att en enskild felkonfigurerad webhook förbrukar orimligt mycket resurser.

Ljudwebhooks har ytterligare två gränser. En ljudpayload större än 50 MiB levereras en gång och försöks inte igen, och köade ljudåterförsök för en enskild webhook får sammanlagt 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 på varandra följande leveransfel har inträffat.
• Webhooken har aldrig levererats korrekt, eller så skedde den senaste lyckade leveransen för mer än 7 dagar sedan.

När en webhook inaktiveras automatiskt får arbetsytans administratörer en e-postnotifikation. Webhooken måste återaktiveras manuellt från inställningssidan innan den återupptar leveranserna.

Integration

För att integrera med webhooks skapar du en endpoint-hanterare som tar emot webhook-händelsedata som POST-begäranden. Efter att ha validerat signaturen bör hanteraren snabbt returnera HTTP 200 för att bekräfta att den tagits emot. Upprepade misslyckanden med att returnera ett lyckat svar kan leda till att webhooken inaktiveras automatiskt.

Payloaden vid återförsök är identisk med det ursprungliga leveransförsöket. De som tar emot webhooks kan inte skilja mellan en första leverans och ett återförsök enbart utifrån payloaden, så utforma din hanterare så att den är idempotent — att behandla 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-payload

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