Phil Leggetter Phil Leggetter

How to Test and Replay Retell AI Webhooks Locally with Hookdeck

Published · Updated


Retell AI sends webhooks as a call progresses: call_started when it begins, call_ended when it finishes, and call_analyzed when post-call analysis completes. Retell blocks localhost and private IP ranges, so testing a handler on your machine needs a public URL in front of it. Every test also means placing another call.

In this guide you receive those events locally with the Hookdeck CLI and replay them from a single call:

  1. Set up a local webhook endpoint
  2. Create a Retell source in Hookdeck
  3. Start the Hookdeck CLI
  4. Configure the webhook in Retell and place a test call
  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 Express handler logs the event name and call ID:

mkdir retell-webhook-test && cd retell-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/retell", (req, res) => {
  const { event, call } = req.body;
  console.log(event, call?.call_id);
  res.sendStatus(200);
});

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

Start it with node index.js. Event Gateway verifies the X-Retell-Signature before forwarding, so the handler doesn't. See how to secure and verify Retell AI webhooks for the details.

Step 2: Create a Retell source in Hookdeck

Create a free Hookdeck account. In the dashboard, create a source named retell, pick Retell as the source type, and paste your Retell API key into Webhook Signing Secret. Use the API key that shows the webhook badge in the Retell dashboard, because Retell signs webhooks with that key. To choose it, open Settings, then API Keys, and select Set as Webhook Key.

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 retell --path /webhooks/retell

The CLI prints the source's public URL and forwards events on that source to http://localhost:3000/webhooks/retell.

Step 4: Configure the webhook in Retell and place a test call

In the Retell dashboard, enter the Hookdeck source URL in the Webhooks tab to receive events for every agent in the account. To test with one agent only, set that agent's webhook_url to the Hookdeck source URL. An agent-level URL overrides the account-level one, so events for that agent go only to the agent's URL.

Place a test call to your agent. A phone call and a web call send the same events: call_started, call_ended, and call_analyzed by default.

call_analyzed includes call_analysis and arrives after the call ends, at the same time as call_ended for a short call. A call that never connects sends only call_ended and call_analyzed.

Each event shows up in the CLI, in your handler's console output, and in the Hookdeck dashboard with its headers and body. 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

One call gives you all three events, stored by Event Gateway. Replay them against your handler instead of placing more calls.

  • 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. Retell retries up to three times when it doesn't receive a 2xx within 10 seconds, so the same event can arrive more than once in production. Make your handler idempotent, keyed on the event name and call_id.

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

A Retell source with hookdeck listen gives your local handler a public URL, signature verification, and a stored copy of every call event to replay. When the handler is ready, change the connection's destination to your deployed URL.

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