Phil Leggetter Phil Leggetter

How to Test and Replay Vapi Webhooks Locally with Hookdeck

Published · Updated


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:

mkdir vapi-webhook-test && cd vapi-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/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. 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 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:

  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 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.

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 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.

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.
  • 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 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.

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