Phil Leggetter Phil Leggetter

How to Test and Replay ElevenLabs Webhooks Locally with Hookdeck

Published · Updated


ElevenLabs sends a post_call_transcription webhook and a post_call_audio webhook after a conversation with one of your agents ends and its analysis completes. To test your handler, you need a public HTTPS URL, and each test means holding another call with your agent.

In this guide you receive those webhooks on a local Express server through the Hookdeck CLI, then replay the stored events while you fix your handler. The steps are:

  1. Set up a local webhook endpoint
  2. Create an ElevenLabs source in Hookdeck
  3. Start the Hookdeck CLI
  4. Configure the webhook in ElevenLabs and trigger an event
  5. Replay events while you fix your handler

Step 1: Set up a local webhook endpoint

Any HTTP server that logs the request body will do. This minimal Express handler logs the event type and conversation ID:

mkdir elevenlabs-webhook-test && cd elevenlabs-webhook-test
npm init -y
npm install express

Create index.js:

const express = require("express");
const app = express();
app.use(express.json());

app.post("/webhooks/elevenlabs", (req, res) => {
  const { type, event_timestamp, data } = req.body;
  console.log(type, event_timestamp, data?.conversation_id);
  res.sendStatus(200);
});

app.listen(3000, () => console.log("Listening on :3000"));

Start it with node index.js. The handler doesn't verify the ElevenLabs-Signature itself, because Event Gateway verifies it once you add the signing secret in Step 4. To see how, read how to secure and verify ElevenLabs webhooks.

Step 2: Create an ElevenLabs source in Hookdeck

Create a free Hookdeck account. In the dashboard, create a source named elevenlabs and pick ElevenLabs as the source type. ElevenLabs shows the signing secret once, when you create the webhook in Step 4, so create the source first and paste the secret into Webhook Signing Secret afterward.

Step 3: Start the Hookdeck CLI

Install the Hookdeck CLI:

  npm install hookdeck-cli -g
  
  
  yarn global add hookdeck-cli
  
  
    brew install hookdeck
    
    
  1.     scoop bucket add hookdeck https://github.com/hookdeck/scoop-hookdeck-cli.git
        
        
  2.   scoop install hookdeck
      
      
  1. Download the latest release's tar.gz file.

  2.     tar -xvf hookdeck_X.X.X_linux_x86_64.tar.gz
        
        
  3.   ./hookdeck
      
      

Log in, which opens a browser:

hookdeck login

Then listen on your port, naming the source and the path your handler uses:

hookdeck listen 3000 elevenlabs --path /webhooks/elevenlabs

The CLI prints the source's public URL and forwards every event on that source to http://localhost:3000/webhooks/elevenlabs. While hookdeck listen is running, the terminal shows each event as it arrives.

Step 4: Configure the webhook in ElevenLabs and trigger an event

In your ElevenLabs workspace, create a webhook with HMAC authentication and the Hookdeck source URL, following the ElevenLabs webhooks documentation. Copy the signing secret ElevenLabs shows you into the Hookdeck source's Webhook Signing Secret field.

Then connect the webhook to an agent. In the ElevenLabs agents dashboard, open your agent, go to Settings, and choose the webhook under Post-call webhooks. The ElevenLabs post-call webhook documentation lists the event types you can send: transcript, audio and call_initiation_failure among them.

Hold a short test conversation with the agent. An agent with no first message stays silent until the caller speaks, so give it one.

About a second after the call ends, once analysis completes, a post_call_transcription event and a post_call_audio event arrive. You see them in the CLI, in your handler's console output, and in the Hookdeck dashboard with their headers and full bodies. Each request has an ElevenLabs-Signature: t=<timestamp>,v0=<signature> header.

Expect a post_call_transcription body of about 53 KB for a voice call and a post_call_audio body of about 3.5 MB, because the audio webhook contains the whole conversation as a base64 MP3. A text-only conversation sends a 435-byte post_call_audio body. If your handler logs request bodies, log the type and data.conversation_id and skip the audio payload.

If your handler returns a status other than 2xx, Event Gateway records the failed delivery attempt and retries according to the connection's retry rules.

Step 5: Replay events while you fix your handler

A post_call_transcription payload includes the transcript, analysis, and metadata, and you want to run your code against it many times. You can replay the stored event instead of holding another call.

  • In the CLI: select an event with the arrow keys and press r to retry it against your local server.
  • In the dashboard: open the event and select Retry, or replay the request.
  • From the command line: run hookdeck gateway event retry <event-id>.

Edit your handler, restart it, and replay the same event. ElevenLabs delivers identical payloads on retries, so build your handler to be idempotent. The two post-call events for a conversation share data.conversation_id, so key on type and data.conversation_id together.

Replay isn't limited to a 30-minute window. Event Gateway checks the signature when the request arrives, so an event stored last week replays without a freshness failure. If your own handler calls the SDK's constructEvent, it rejects a timestamp older than 30 minutes, so an old event fails there even though Event Gateway verified it.

If no hookdeck listen session is running when a request arrives, Event Gateway stores the request but doesn't create an event for the CLI. Start the CLI first, then replay the request to create the event.

Conclusion

With a verified ElevenLabs source and hookdeck listen, a single test call gives you a payload to replay for as long as you are working on the handler. When the handler is ready, change the connection's destination to your deployed URL. For a complete example that stores each conversation and shows retries and deduplication, see the post-call transcripts demo.

Try Hookdeck for free. For more, see the guide to ElevenLabs webhooks and how to secure and verify 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.