Hoppa till navigering

Webhooks

Aktivera externa integrationer genom att ta emot webhook-händelser.

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

HändelsetypBeskrivning
post_call_transcriptionEtt samtal i Agents Platform har avslutats och analysen är klar
voice_removal_noticeEn delad röst är planerad att tas bort
voice_removal_notice_withdrawnEn delad röst är inte längre planerad att tas bort
voice_removedEn delad röst har tagits bort och kan inte längre användas
flows_generationEn bild- och videogenerering har slutförts eller misslyckats
flows_template_runEn körning av en mall har slutförts eller misslyckats

Konfiguration

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

HMAC-webhookkonfiguration

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

Händelserna flows_generation och flows_template_run aktiveras båda av en prenumeration: under Välj händelser att lyssna efter markerar du Generering eller mallkörning med Image & Video API slutförd, eller skickar händelsen flows till Uppdatera arbetsytans webhook. En generering eller körning skickar bara sin händelse när dess begäran om att skapa den innehåller fältet webhook.

Webhooks kan när som helst inaktiveras på sidan för allmänna inställningar. 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 den aldrig har levererats. Webhooks som har inaktiverats automatiskt måste återaktiveras på inställningssidan. Webhooks kan tas bort om de inte används av några produkter.

Återförsök

Å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.

Återförsök stöds för ElevenAgents webhooks efter samtal, inklusive händelser för transkribering (post_call_transcription), ljud (post_call_audio) och misslyckad samtalsinitiering (call_initiation_failure).

Schema för återförsök

När ett leveransförsök misslyckas med ett fel som går att försöka igen med försöker systemet upp till 5 gånger med allt längre fördröjningar mellan försöken:

FörsökFördröjning
1Omedelbart
230 sekunder
32 minuter
48 minuter
530 minuter

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 går att försöka igen med

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

  • Statuskoderna 5xx (serverfel som 500, 502, 503 och 504).
  • 429 (Too Many Requests).
  • 408 (Request Timeout).
  • Anslutningsfel och timeout för begäranden.

Begärandefel i intervallet 4xx (som 400, 401, 403 och 404) försöks inte igen, eftersom de vanligtvis tyder på ett konfigurationsproblem som måste åtgärdas manuellt.

Kögränser 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ön tas ytterligare jobb bort tills befintliga återförsök har behandlats. Detta förhindrar att en felkonfigurerad webhook använder för mycket resurser.

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

Beteende vid automatisk inaktivering

Systemet spårar misslyckade leveranser i följd för varje webhook. En webhook inaktiveras automatiskt när båda följande villkor är uppfyllda:

  • 10 eller fler misslyckade leveranser 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 arbetsytans administratörer en e-postnotis. Webhooken måste återaktiveras manuellt på inställningssidan innan den återupptar leveranser.

Integration

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

Payloaden för återförsöket är identisk med det ursprungliga leveransförsöket. Mottagare av 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 — om samma händelse behandlas flera gånger ska resultatet bli detsamma. Använd event_timestamp och händelsespecifika identifierare (som conversation_id) för att avduplicera händelser vid behov.

Fält på toppnivå

FältTypBeskrivning
typestringTyp av händelse
dataobjectData för händelsen
event_timestampnumberNär händelsen inträffade i Unix-tid, UTC

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

Webhooks för borttagning av röster

En arbetsyta tar emot dessa händelser för en delad röst från Voice Library som den har lagt till, när röstens ägare eller ElevenLabs tar bort den från Voice Library.

Meddelande om borttagning (voice_removal_notice)

Rösten har en uppsägningstid. Den kan användas fram till future_removal_timestamp.

Ingen ytterligare händelse skickas när uppsägningstiden löper ut.

Datastruktur för objektet

FältTypBeskrivning
voice_idstringID:t för rösten som är planerad att tas bort
future_removal_timestampnumberNär rösten slutar kunna användas, i Unix-tid, UTC
suggested_voicesarrayUpp till 3 liknande röster. Se Föreslagna röster
{
"type": "voice_removal_notice",
"event_timestamp": 1739537297,
"data": {
"voice_id": "21m00Tcm4TlvDq8ikWAM",
"future_removal_timestamp": 1742129297,
"suggested_voices": [
["https://elevenlabs.io/app/voice-lab/share/a1b2c3d4e5f6/EXAVITQu4vr4xnSDxMaL", "Sarah"]
]
}
}

Meddelande om borttagning återkallat (voice_removal_notice_withdrawn)

Rösten är inte längre planerad att tas bort och kan fortfarande användas.

Datastruktur för objektet

FältTypBeskrivning
voice_idstringID:t för rösten som inte längre ska tas bort
{
"type": "voice_removal_notice_withdrawn",
"event_timestamp": 1739537297,
"data": {
"voice_id": "21m00Tcm4TlvDq8ikWAM"
}
}

Röst borttagen (voice_removed)

Rösten togs bort utan uppsägningstid och kan inte längre användas.

Datastruktur för objektet

FältTypBeskrivning
voice_idstringID:t för rösten som togs bort
suggested_voicesarrayUpp till 3 liknande röster. Se Föreslagna röster
{
"type": "voice_removed",
"event_timestamp": 1739537297,
"data": {
"voice_id": "21m00Tcm4TlvDq8ikWAM",
"suggested_voices": [
["https://elevenlabs.io/app/voice-lab/share/a1b2c3d4e5f6/EXAVITQu4vr4xnSDxMaL", "Sarah"]
]
}
}

Föreslagna röster

Varje objekt i suggested_voices är en array med två objekt: röstens delnings-URL i Voice Library och sedan röstens namn. Listan kan vara tom.

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.

Exempel på webhook-hanterare med FastAPI:

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