Developing locally
Learn how to receive server events in your local development environment.
Use the Vapi CLI webhook forwarder along with a tunneling service to test webhooks locally:
Important: The vapi listen command is a local forwarder only - it does NOT provide a public URL or tunnel. You must use a separate tunneling service (like ngrok) to expose the CLI’s port (default 4242) to the internet, then configure your Vapi webhook URLs to use the tunnel’s public URL.
Learn more about the Vapi CLI →
If you prefer to skip the CLI and connect ngrok directly to your application, follow the guide below.
When Vapi dispatches events to a server, it must be able to reach the server via the open Internet.
If your API is already live in production, it will be accessible via a publicly known URL. But, during development, your server will often be running locally on your machine.
localhost is an alias for the IP address 127.0.0.1. This address is called the “loopback”
address and forwards the network request within the machine itself.
To receive server events locally, we will need a public address on the Internet that can receive traffic and forward it to our local machine.
We will be using a service called ngrok to create a secure tunnel to our local machine. The flow will look like the following:
We will start our server locally so it is listening for http traffic. We will take note of the port our server is running on.
We will use the ngrok command to start the ngrok agent on our
machine. This will establish a connection from your local machine to ngrok’s servers.
First, ensure that your API is running locally. This could be a Node.js server, a Python server, or any other server that can receive HTTP requests.
Take note of the port that your server is running on. For example, if your server is running on port 8080, you should be able to access it at http://localhost:8080 in your browser.
Next we will install & run Ngrok agent to establish the forwarding pathway for Internet traffic:
Install the Ngrok agent by following Ngrok’s quickstart
guide. Once complete, we will have the ngrok command
available in our terminal.
You will see an output from the Ngrok Agent CLI that looks like the following:
Copy this public URL that Ngrok provides. This URL will be accessible from the open Internet and will forward traffic to your local machine.
You can now use this as a server URL in the various places you can set server URLs in Vapi.
This URL will change every time that you run the ngrok command. If you’d like this URL to be the
same every Ngrok session, look into static domains on
Ngrok.
We will now be able to see call events come through as POST requests, & can log payloads to our terminal.
Feel free to follow any of our quickstart guides to get started with building assistants & conducting calls.
Here’s a list of a few things to recheck if you face issues seeing payloads:
ngrok http {your_port} commandPOST endpoint/callbacks/vapi)