Gareth Wilson Gareth Wilson

Guide to ElevenLabs Webhooks: Features and Best Practices

Published · Updated


ElevenLabs webhooks notify your application when an async voice or call job reports back: a call transcription is ready, or a voice is scheduled for removal or removed. If you're building on ElevenLabs, webhooks are how these long-running jobs tell you they're done without polling.

This guide covers how ElevenLabs webhooks work, the events you'll handle, how to verify the ElevenLabs-Signature with the official SDK, and the best practices for production.

What are ElevenLabs webhooks?

ElevenLabs webhooks are JSON POSTs delivered to a URL you configure. Each is signed with an ElevenLabs-Signature header formatted t=<timestamp>,v0=<signature>. The signature is an HMAC-SHA256 (hex) over <timestamp> + "." + raw_body, keyed with your webhook signing secret. The header can carry more than one v0= value, and any one matching is valid. ElevenLabs rejects deliveries outside a 30-minute window to guard against replay. The official @elevenlabs/elevenlabs-js SDK verifies all of this for you.

ElevenLabs webhook features

FeatureDetails
ConfigurationElevenLabs dashboard > Settings > General > Webhooks
Signature headerElevenLabs-Signature, formatted t=<ts>,v0=<sig>
Signature schemeHMAC-SHA256 (hex) over <timestamp>.<raw_body>
Replay window30 minutes, always enforced by the SDKs; one v0= value per header
SDK@elevenlabs/elevenlabs-js webhooks.constructEvent (Node); elevenlabs >= 2.4.0 webhooks.construct_event (Python)
Delivery200 expected within 10s; auto-disable after 10 consecutive failures; may arrive out of order

Common events

ElevenLabs has four event types:

EventFires when
post_call_transcriptionCall analysis and transcription complete
voice_removal_noticeA voice is scheduled for removal
voice_removal_notice_withdrawnA voice removal notice is cancelled
voice_removedA voice is removed from the account

The payload envelope is { type, data, event_timestamp }; branch on type.

See ElevenLabs webhook payloads in action. Inspect and replay sample ElevenLabs webhook payloads in Hookdeck Inspect — no account or setup required.

Setting up ElevenLabs webhooks

In the ElevenLabs dashboard, go to Settings > General > Webhooks, add your endpoint URL, select events, and create the webhook. Copy the signing secret immediately (it won't be shown again) into ELEVENLABS_WEBHOOK_SECRET. Install the current SDK with npm install @elevenlabs/elevenlabs-js, not the outdated elevenlabs v1.x package.

Securing ElevenLabs webhooks

Use the official SDK's webhooks.constructEvent, which verifies the ElevenLabs-Signature and returns the parsed event (throwing on an invalid signature). It needs the raw request body, so capture it before parsing.

const { ElevenLabsClient } = require("@elevenlabs/elevenlabs-js");

const elevenlabs = new ElevenLabsClient({ apiKey: process.env.ELEVENLABS_API_KEY || "webhook-only" });
const SECRET = process.env.ELEVENLABS_WEBHOOK_SECRET;

app.post("/webhooks/elevenlabs", express.raw({ type: "application/json" }), async (req, res) => {
  const signature = req.headers["elevenlabs-signature"];
  const rawBody = Buffer.isBuffer(req.body) ? req.body.toString("utf8") : req.body;
  try {
    const event = await elevenlabs.webhooks.constructEvent(rawBody, signature, SECRET);
    res.sendStatus(200); // acknowledge fast
    processQueue.add(event); // branch on event.type, async
  } catch {
    res.sendStatus(401); // invalid signature or stale timestamp
  }
});

In Python, use webhooks.construct_event from the elevenlabs package (version 2.4.0 or later). It checks the signature and the 30-minute window and returns the parsed event as a dict, raising BadRequestError on failure. It takes the raw body as a str, so decode the request bytes first:

import os

from elevenlabs import ElevenLabs
from elevenlabs.errors import BadRequestError
from fastapi import FastAPI, HTTPException, Request

app = FastAPI()
elevenlabs = ElevenLabs(api_key=os.environ.get("ELEVENLABS_API_KEY") or "webhook-only")
SECRET = os.environ["ELEVENLABS_WEBHOOK_SECRET"]

@app.post("/webhooks/elevenlabs")
async def elevenlabs_webhook(request: Request):
    raw_body = (await request.body()).decode("utf-8")
    signature = request.headers.get("elevenlabs-signature")
    try:
        event = elevenlabs.webhooks.construct_event(raw_body, signature, SECRET)
    except BadRequestError:
        raise HTTPException(status_code=401)  # invalid signature or stale timestamp
    # branch on event["type"], ideally from a queue
    return {"status": "ok"}

Both SDKs compare signatures with a plain string comparison rather than a constant-time one, and both always enforce the 30-minute window. If either matters to you, verify manually: an HMAC-SHA256 of <t>.<raw body> keyed with the secret, compared with crypto.timingSafeEqual or hmac.compare_digest.

Make ElevenLabs webhooks production-ready. Hookdeck Event Gateway verifies the ElevenLabs-Signature, deduplicates, and durably queues every event.

ElevenLabs webhook limitations and pain points

The signed message is timestamp.body

The Problem: The HMAC is over <timestamp> + "." + raw_body, not the body alone. Signing the body by itself never matches.

Why It Happens: ElevenLabs binds the timestamp into the signed message, Stripe-style.

Workarounds:

  • Let the SDK reconstruct and verify it, or build timestamp + "." + body manually.

How Hookdeck Can Help: Hookdeck verifies the signature, so your app receives pre-verified events.

Use the current SDK, not the old package

The Problem: In Node, the verification helper lives in @elevenlabs/elevenlabs-js; the outdated elevenlabs (v1.x) npm package doesn't provide it. In Python, construct_event only exists from version 2.4.0 of the elevenlabs package.

Why It Happens: The Node SDK was renamed, and the Python helper was added later.

Workarounds:

  • Install @elevenlabs/elevenlabs-js for Node and elevenlabs>=2.4.0 for Python.

How Hookdeck Can Help: Hookdeck verifies the signature, so a missing or renamed SDK isn't a blocker.

The 30-minute replay window

The Problem: Deliveries older than 30 minutes are rejected. A slow queue, clock skew, or replaying old events for testing trips this.

Why It Happens: ElevenLabs enforces a 30-minute freshness window.

Workarounds:

  • Keep server clocks in sync, and don't replay events older than the window into the verifier.
  • The SDKs can't widen the window, so verify manually if you need to accept older deliveries.

How Hookdeck Can Help: Hookdeck verifies the signature on arrival and durably queues events, so downstream slowness doesn't fail verification.

Out-of-order delivery

The Problem: Events may arrive out of order, so a later state can land before an earlier one.

Why It Happens: Delivery isn't strictly ordered.

Workarounds:

  • Order by event_timestamp, and make handlers idempotent.

How Hookdeck Can Help: Hookdeck durably queues events so your worker can reconcile ordering at its own pace.

Best practices

Verify with the official SDK over the raw body

Use webhooks.constructEvent(rawBody, signature, secret) in Node and webhooks.construct_event(raw_body, signature, secret) in Python, passing the raw body as a string.

Respect the 30-minute window

Reject stale deliveries. ElevenLabs sends one v0= value per header, and the SDKs check only one.

Order by event_timestamp

Events can arrive out of order, so sort on event_timestamp and dedupe.

Acknowledge fast, process asynchronously

Return 200 within 10 seconds and defer work to a queue. See why to process webhooks asynchronously.

Conclusion

ElevenLabs webhooks are verified with an ElevenLabs-Signature HMAC-SHA256 over <timestamp>.<raw_body>, formatted t=<ts>,v0=<sig> with a 30-minute window. Use the official @elevenlabs/elevenlabs-js constructEvent in Node or construct_event from elevenlabs 2.4.0+ in Python, respect the freshness window, and order by event_timestamp.

Hookdeck verifies the signature, deduplicates, and durably queues every event, so your app only ever processes verified, unique events.

For the delivery side, including timeouts and concurrency limits for the AI workloads that consume these events, see the AI Agents & LLMs use case.

Get started with Hookdeck for free and handle ElevenLabs webhooks reliably in minutes.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.