Webhooks

Overview

Certain events within ElevenLabs can be configured to trigger webhooks, allowing external applications and systems to receive and process these events as they occur. Currently supported event types include:

Configuration

Webhooks can be created, disabled and deleted from the general settings page. For users within Workspaces, only the workspace admins can configure the webhooks for the workspace.

After creation, the webhook can be selected to listen for events within product settings such as Agents Platform.

Webhooks can be disabled from the general settings page at any time. Webhooks that repeatedly fail are auto-disabled if there are 10 or more consecutive failures and the last successful delivery was more than 7 days ago or has never been successfully delivered. Auto-disabled webhooks require re-enabling from the settings page. Webhooks can be deleted if not in use by any products.

Retries

Webhook retries can be enabled per webhook to automatically reattempt delivery when a request fails. Retries are disabled by default. Enable retries when creating or updating a webhook through the API or in the webhook settings.

Retry schedule

When a delivery attempt fails with a retryable error, the system retries up to 5 times with increasing delays between attempts:

A small random jitter (up to 10% of the delay) is added to each retry to distribute load and avoid thundering herd problems.

Retryable errors

Not all failures trigger a retry. Only the following HTTP status codes are considered retryable:

• 5xx status codes (server errors such as 500, 502, 503, 504).
• 429 (Too Many Requests).
• 408 (Request Timeout).

Request errors in the 4xx range (such as 400, 401, 403, 404) are not retried, since they typically indicate a configuration issue that requires manual correction.

Per-webhook queue limits

Each webhook is limited to 100 pending retry jobs. If a webhook accumulates more than 100 queued retries, additional jobs are dropped until existing retries are processed. This prevents a single misconfigured webhook from consuming excessive resources.

Auto-disable behavior

The system tracks consecutive delivery failures for each webhook. A webhook is automatically disabled when both of the following conditions are met:

• 10 or more consecutive delivery failures have occurred.
• The webhook has never been successfully delivered, or the last successful delivery was more than 7 days ago.

When a webhook is auto-disabled, workspace admins receive an email notification. The webhook must be manually re-enabled from the settings page before it resumes delivery.

Integration

To integrate with webhooks, create an endpoint handler to receive webhook event data as POST requests. After validating the signature, the handler should return HTTP 200 promptly to indicate successful receipt. Repeated failure to return a success response may result in the webhook becoming automatically disabled.

The retry payload is identical to the original delivery attempt. Webhook consumers cannot distinguish between an initial delivery and a retry from the payload alone, so design your handler to be idempotent — processing the same event multiple times should produce the same result. Use the event_timestamp and event-specific identifiers (such as conversation_id) to deduplicate events if needed.

Top-level fields

Example webhook payload

1
{
2
  "type": "post_call_transcription",
3
  "event_timestamp": 1739537297,
4
  "data": {
5
    "agent_id": "xyz",
6
    "conversation_id": "abc",
7
    "status": "done",
8
    "transcript": [
9
      {
10
        "role": "agent",
11
        "message": "Hey there angelo. How are you?",
12
        "tool_calls": null,
13
        "tool_results": null,
14
        "feedback": null,
15
        "time_in_call_secs": 0,
16
        "conversation_turn_metrics": null
17
      },
18
      {
19
        "role": "user",
20
        "message": "Hey, can you tell me, like, a fun fact about 11 Labs?",
21
        "tool_calls": null,
22
        "tool_results": null,
23
        "feedback": null,
24
        "time_in_call_secs": 2,
25
        "conversation_turn_metrics": null
26
      },
27
      {
28
        "role": "agent",
29
        "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...",
30
        "tool_calls": null,
31
        "tool_results": null,
32
        "feedback": null,
33
        "time_in_call_secs": 9,
34
        "conversation_turn_metrics": {
35
          "convai_llm_service_ttfb": {
36
            "elapsed_time": 0.3704247010173276
37
          },
38
          "convai_llm_service_ttf_sentence": {
39
            "elapsed_time": 0.5551181449554861
40
          }
41
        }
42
      }
43
    ],
44
    "metadata": {
45
      "start_time_unix_secs": 1739537297,
46
      "call_duration_secs": 22,
47
      "cost": 296,
48
      "deletion_settings": {
49
        "deletion_time_unix_secs": 1802609320,
50
        "deleted_logs_at_time_unix_secs": null,
51
        "deleted_audio_at_time_unix_secs": null,
52
        "deleted_transcript_at_time_unix_secs": null,
53
        "delete_transcript_and_pii": true,
54
        "delete_audio": true
55
      },
56
      "feedback": {
57
        "overall_score": null,
58
        "likes": 0,
59
        "dislikes": 0
60
      },
61
      "authorization_method": "authorization_header",
62
      "charging": {
63
        "dev_discount": true
64
      },
65
      "termination_reason": ""
66
    },
67
    "analysis": {
68
      "evaluation_criteria_results": {},
69
      "data_collection_results": {},
70
      "call_successful": "success",
71
      "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."
72
    },
73
    "conversation_initiation_client_data": {
74
      "conversation_config_override": {
75
        "agent": {
76
          "prompt": null,
77
          "first_message": null,
78
          "language": "en"
79
        },
80
        "tts": {
81
          "voice_id": null
82
        }
83
      },
84
      "custom_llm_extra_body": {},
85
      "dynamic_variables": {
86
        "user_name": "angelo"
87
      }
88
    }
89
  }
90
}

Authentication

It is important for the listener to validate all incoming webhooks. Webhooks currently support authentication via HMAC signatures. Set up HMAC authentication by:

• Securely storing the shared secret generated upon creation of the webhook
• Verifying the ElevenLabs-Signature header in your endpoint using the SDK

The JavaScript SDK exposes constructEvent; the Python SDK exposes construct_event with rawBody, sig_header, and secret (these are not named payload / signature in Python). Both verify the signature, validate the timestamp, and parse the JSON payload.

1
from dotenv import load_dotenv
2
from fastapi import FastAPI, Request
3
from fastapi.responses import JSONResponse
4
from elevenlabs.client import ElevenLabs
5
import os
6
7
load_dotenv()
8
9
app = FastAPI()
10
elevenlabs = ElevenLabs(
11
    api_key=os.getenv("ELEVENLABS_API_KEY"),
12
)
13
14
WEBHOOK_SECRET = os.getenv("WEBHOOK_SECRET")
15
16
@app.post("/webhook")
17
async def receive_message(request: Request):
18
    payload = await request.body()
19
    signature = request.headers.get("elevenlabs-signature")
20
21
    try:
22
        event = elevenlabs.webhooks.construct_event(
23
            rawBody=payload.decode("utf-8"),
24
            sig_header=signature,
25
            secret=WEBHOOK_SECRET,
26
        )
27
    except Exception as e:
28
        return JSONResponse(content={"error": "Invalid signature"}, status_code=401)
29
30
    # construct_event returns a dict (parsed JSON), not an object with attributes
31
    if event.get("type") == "post_call_transcription":
32
        print(f"Received transcription: {event.get('data')}")
33
34
    return {"status": "received"}