Phil Leggetter Phil Leggetter

How to Secure and Verify ElevenLabs Webhooks with Hookdeck

Published · Updated


ElevenLabs signs each webhook with an ElevenLabs-Signature header. If your handler stores a transcript or triggers a follow-up when a post_call_transcription event arrives, check that header, because anyone who learns your endpoint URL can send it a forged event. This guide shows how to verify the signature in your own handler with the ElevenLabs SDK, and how to have Hookdeck Event Gateway verify it before the request reaches your application.

For the full picture of ElevenLabs events and delivery behavior, see the guide to ElevenLabs webhooks.

How ElevenLabs signs webhooks

When you create a webhook in your ElevenLabs workspace, ElevenLabs generates a signing secret. Every delivery then includes an ElevenLabs-Signature header. The ElevenLabs webhooks documentation tells you to verify it with the SDK, which checks the signature and the timestamp and parses the JSON.

The Event Gateway ElevenLabs source type implements the same check on the wire format:

  • Header: ElevenLabs-Signature, in the form t=<timestamp>,v0=<signature>.
  • Signed message: the timestamp, a ., then the raw request body.
  • Algorithm: HMAC-SHA256 with your signing secret, hex-encoded.

Because the timestamp is part of the signed message, a signature computed over the body alone never matches. The body must also be the raw bytes ElevenLabs sent, not a re-serialized copy of parsed JSON.

How to verify ElevenLabs webhooks manually

Install the current SDK. The @elevenlabs/elevenlabs-js package provides webhooks.constructEvent:

npm install @elevenlabs/elevenlabs-js

Read the raw body, pass it with the header and your secret, and reject anything that throws:

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

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

app.post(
  "/webhooks/elevenlabs",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    try {
      const event = await elevenlabs.webhooks.constructEvent(
        req.body.toString("utf8"),
        req.headers["elevenlabs-signature"],
        process.env.ELEVENLABS_WEBHOOK_SECRET
      );
      res.sendStatus(200);
      console.log(event.type);
    } catch (err) {
      res.sendStatus(401);
    }
  }
);

app.listen(3000);

This works, and it leaves verification code, the secret, and the raw-body requirement in every service that receives ElevenLabs events. A second service, or a staging environment with its own webhook, repeats all of it.

How to verify ElevenLabs webhooks with Hookdeck

Hookdeck Event Gateway verifies the signature when the request arrives at your source URL. Requests that fail verification are recorded as rejected and never reach your application.

ElevenLabs shows the signing secret once, when you create the webhook, and the webhook needs the Hookdeck source URL. Create the source first and add the secret afterward:

  1. Create a free Hookdeck account.
  2. In the Hookdeck dashboard, create a new source and pick ElevenLabs as the source type.
  3. Create a connection from the source to a destination, such as your application's webhook URL, and copy the source URL.
  4. In ElevenLabs, create a webhook with the Hookdeck source URL and HMAC authentication, following the ElevenLabs webhooks documentation, and copy the signing secret it shows.
  5. Paste the secret into the Hookdeck source's Webhook Signing Secret field.
  6. Open your agent's Settings in the ElevenLabs dashboard, choose the webhook under Post-call webhooks, and select the events to send: transcript, audio and call_initiation_failure.
  7. Finish a call with the agent to trigger an event.

In the Hookdeck dashboard, the request appears under your source. A valid delivery becomes an event and is forwarded to your destination.

A request with a bad signature gets a 200 response, so the sender sees nothing unusual. Event Gateway records the request as rejected with the cause VERIFICATION_FAILED and creates no event.

To check whether your secret is right, look at the request list, not the response status. See requests for how rejected requests are retried.

Your handler no longer needs constructEvent. It can parse the JSON body and branch on type.

Inspect the webhooks a call sends

A call produces a post_call_transcription webhook and a post_call_audio webhook about a second after hang-up, once the analysis has finished.

In test calls, the post_call_transcription body was about 53 KB for a voice call (6 to 18 KB for short text-only conversations). The post_call_audio body was about 3.5 MB, because it contains the whole conversation as a base64 MP3.

A text-only conversation has no audio, and its post_call_audio body was 435 bytes. Event Gateway accepted a signed 8 MB post_call_transcription and delivered it.

For a working example, see the post-call transcripts demo. Its npm run setup command creates the source, the connection and the ElevenLabs webhook, and sets the secret on the source.

Its npm run probe command sends one correctly signed request, which verifies, and one badly signed request, which gets a 200 and shows as VERIFICATION_FAILED with no event.

The demo also runs the SDK's constructEvent on each forwarded request as a display-only check. It returned ok on every request from a live call. A replay of an event older than 30 minutes shows a tolerance error there, because the SDK rejects older timestamps while the event is still stored.

What Event Gateway verifies

Event Gateway recomputes HMAC-SHA256 over <timestamp>.<raw body> with your secret and compares it with the v0= values in the header.

Deduplicate the two post-call webhooks

A call's post_call_transcription and post_call_audio webhooks share the same data.conversation_id, so deduplicating on that field alone drops the audio after the transcription arrives. To process each event once, deduplicate on body.type and body.data.conversation_id together, and make your handler idempotent. The signature covers a timestamp, so a request sent again later can have a different ElevenLabs-Signature. Name those two fields in the rule instead of comparing the whole request:

{
  "type": "deduplicate",
  "window": 3600000,
  "include_fields": ["body.type", "body.data.conversation_id"]
}

In the demo, sending the same signed post_call_transcription twice produced one delivery to the app.

Verify that requests to your app come from Hookdeck

Verification at the source URL covers requests arriving at Event Gateway. To cover the request from Hookdeck to your application, enable Hookdeck webhook signature verification, so your application can confirm each request came from Hookdeck and not from someone who found your destination URL.

Conclusion

ElevenLabs signs each webhook with an HMAC over the timestamp and raw body. You can verify it in every handler with constructEvent, or configure an ElevenLabs source in Event Gateway once and forward only verified events.

Get started with Hookdeck and continue with how to test and replay ElevenLabs webhooks locally. For more background, see the guide to ElevenLabs webhooks.


Phil Leggetter

Phil Leggetter

Head of Developer and Agentic Experiences

Phil is Head of Developer and Agentic Experiences at Hookdeck with expertise in real-time communications technologies, and creator of the AAARRRP Developer Relations strategy framework.