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 Conversational AI.

Webhooks can be disabled from the general settings page at any time. Webhooks that repeatedly fail are auto disabled after 10 consecutive failures over 7 or more days and require re-enabling from the settings page. Webhooks can be deleted if not in use by any products.

Integration

To integrate with webhooks, the listener should create an endpoint handler to receive the webhook event data POST requests. After validating the signature, the handler should quickly return HTTP 200 to indicate successful receipt of the webhook event, repeat failure to correctly return may result in the webhook becoming automatically disabled. Each webhook event is dispatched only once, refer to the API for methods to poll and get product specific data.

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
    ]
11
  }
12
}

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 shared secret

The ElevenLabs-Signature takes the following format:

1
t=timestamp,v0=hash

The hash is equivalent to the hex encoded sha256 HMAC signature of timestamp.request_body. Both the hash and timestamp should be validated, an example is shown here:

1
from fastapi import FastAPI, Request
2
import time
3
import hmac
4
from hashlib import sha256
5
6
app = FastAPI()
7
8
# Example webhook handler
9
@app.post("/webhook")
10
async def receive_message(request: Request):
11
    payload = await request.body()
12
    headers = request.headers.get("elevenlabs-signature")
13
    if headers is None:
14
        return
15
    timestamp = headers.split(",")[0][2:]
16
    hmac_signature = headers.split(",")[1]
17
18
    # Validate timestamp
19
    tolerance = int(time.time()) - 30 * 60
20
    if int(timestamp) < tolerance
21
        return
22
23
    # Validate signature
24
    full_payload_to_sign = f"{timestamp}.{payload.decode('utf-8')}"
25
    mac = hmac.new(
26
        key=secret.encode("utf-8"),
27
        msg=full_payload_to_sign.encode("utf-8"),
28
        digestmod=sha256,
29
    )
30
    digest = 'v0=' + mac.hexdigest()
31
    if hmac_signature != digest:
32
        return
33
34
    # Continue processing
35
36
    return {"status": "received"}