# How to Test and Replay Vapi Webhooks Locally with Hookdeck

Vapi posts the server messages you list in an assistant's `serverMessages` to your Server URL. They include `status-update` when a call starts and ends, and `end-of-call-report` after it ends, which has the transcript, recording URLs and end reason.

To build a handler for them you need a public HTTPS URL for your machine, and every test needs another call.

In this guide you receive those messages on a local Express server through the Hookdeck CLI and replay them. The steps are:

1. Set up a local webhook endpoint
2. Create a Vapi source in Hookdeck
3. Start the Hookdeck CLI
4. Configure the Server URL in Vapi 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. Vapi nests the event type under `message.type`, so this Express handler reads it from there:

```bash
mkdir vapi-webhook-test && cd vapi-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/vapi", (req, res) => {
  const { message } = req.body;
  console.log(message.type, message.call?.id);
  res.sendStatus(200);
});

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

```

Start it with `node index.js`. Event Gateway verifies the signature before it forwards an event, so the handler doesn't.

## Step 2: Create a Vapi source in Hookdeck

Create a [free Hookdeck account](https://dashboard.hookdeck.com/signup). In the dashboard, create a source named `vapi` and pick **Vapi** as the source type. Paste the secret from a Vapi HMAC credential into **Webhook Signing Secret**, and set the algorithm, encoding, and signature header to match the credential.

Follow [how to secure and verify Vapi webhooks](/webhooks/platforms/how-to-secure-and-verify-vapi-webhooks-with-hookdeck) to create the credential. Use `payloadFormat: "{body}"` and `includeTimestamp: false`, so Vapi signs the raw body and the signature in `x-signature` is a hex digest.

## 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 vapi --path /webhooks/vapi

```

The CLI prints the source's public URL and forwards events on that source to `http://localhost:3000/webhooks/vapi`. Vapi's own `vapi listen` command is a local forwarder that doesn't create a public tunnel, so the Hookdeck URL is the one to register.

## Step 4: Configure the Server URL in Vapi and place a test call

In the Vapi dashboard, open your assistant, go to the **Advanced** tab, and set the Hookdeck source URL in **Webhook Server**, with your HMAC credential attached. You can also set it through the `server` object (`url` and `credentialId`) on the assistant, phone number, or tool. See the Vapi documentation on [setting server URLs](https://docs.vapi.ai/server-url/setting-server-urls).

Set `serverMessages` on the assistant to the messages you want, for example `["status-update", "end-of-call-report", "tool-calls"]`. Place a test call to the assistant.

You see a `status-update` when the call starts, another when it ends, and an `end-of-call-report` a second or two later. The [Vapi server events reference](https://docs.vapi.ai/server-url/events) lists the fields in each message.

Expect bodies of about 5 to 40 KB. In two test calls, the first `status-update` was about 5.5 KB and the `end-of-call-report` was 23 KB for a 43-second call and 39 KB for a 100-second call, because the report includes the call's messages and recording URLs.

Every event appears 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

Replay matters most for `end-of-call-report`, because it is the largest message and holds the transcript and recording URLs. Instead of calling the assistant again, resend the stored event.

* **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. A message can arrive more than once, for example when a delivery is retried, so make your handler idempotent, keyed on `message.call.id` and `message.type`.

> 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 Vapi source with `hookdeck listen` gives your local handler a public URL, signature verification, and a stored copy of each call event to replay. When the handler is ready, change the connection's destination to your deployed URL. For a complete example with one source per client and a tool that answers back into a live call, see the [Vapi agency routing demo](https://github.com/hookdeck/hookdeck-demos/tree/main/vapi/agency-routing).

[Try Hookdeck for free](https://dashboard.hookdeck.com/signup). For more, see the [guide to Vapi webhooks](/webhooks/platforms/guide-to-vapi-webhooks-features-and-best-practices) and [how to secure and verify Vapi webhooks](/webhooks/platforms/how-to-secure-and-verify-vapi-webhooks-with-hookdeck).