# How to Test and Replay Retell AI Webhooks Locally with Hookdeck

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](https://docs.retellai.com/features/webhook-overview), 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:

```bash
mkdir retell-webhook-test && cd retell-webhook-test
npm init -y
npm install express

```

Create `index.js`:

```javascript
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](/webhooks/platforms/how-to-secure-and-verify-retell-webhooks-with-hookdeck) for the details.

## Step 2: Create a Retell source in Hookdeck

Create a [free Hookdeck account](https://dashboard.hookdeck.com/signup). 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](/docs/cli):

Log in, which opens a browser:

```bash
hookdeck login

```

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

```bash
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](https://docs.retellai.com/deploy/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](/docs/retries).

## 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](/docs/requests#replay-a-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](/docs/requests#replay-a-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](https://dashboard.hookdeck.com/signup). For more, see the [guide to Retell AI webhooks](/webhooks/platforms/guide-to-retell-webhooks-features-and-best-practices) and [how to secure and verify Retell AI webhooks](/webhooks/platforms/how-to-secure-and-verify-retell-webhooks-with-hookdeck).