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

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:
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å
Exempel på webhook-payload
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
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
Röst borttagen (voice_removed)
Rösten togs bort utan uppsägningstid och kan inte längre användas.
Datastruktur för objektet
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.
Python
JavaScript
Exempel på webhook-hanterare med FastAPI: