Local webhook testing
Overview
The vapi listen
command provides a local webhook forwarding service that receives events and forwards them to your local development server. This helps you debug webhook integrations during development.
Important: vapi listen
does NOT provide a public URL or tunnel. You’ll need to use a separate tunneling solution like ngrok to expose your local server to the internet.
In this guide, you’ll learn to:
- Set up local webhook forwarding with a tunneling service
- Debug webhook events in real-time
- Configure advanced forwarding options
- Handle different webhook types
No automatic tunneling: The vapi listen
command is a local forwarder only. It does not create a public URL or tunnel to the internet. You must use a separate tunneling service (like ngrok) and configure your Vapi webhook URLs manually.
Quick start
Set up a tunnel to your local machine
Use a tunneling service like ngrok to create a public URL:
Note the public URL provided by your tunneling service (e.g., https://abc123.ngrok.io
)
How it works
Current implementation: The vapi listen
command acts as a local webhook forwarder only. It receives webhook events on a local port (default 4242) and forwards them to your specified endpoint. To receive events from Vapi, you must:
- Use a tunneling service (ngrok, localtunnel, etc.) to expose port 4242 to the internet
- Configure your Vapi webhook URLs to point to the tunnel URL
- The flow is: Vapi → Your tunnel URL → vapi listen (port 4242) → Your local server
Basic usage
Standard forwarding
Forward to your local development server:
Custom port
Use a different port for the webhook listener:
Skip TLS verification
For development with self-signed certificates:
Only use --skip-verify
in development. Never in production.
Understanding the output
When you run vapi listen
, you’ll see:
Webhook event types
The listener forwards all Vapi webhook events:
Call lifecycle events
call-started
- Call initiatedcall-ended
- Call completedcall-failed
- Call encountered an error
Speech events
speech-update
- Real-time transcriptiontranscript
- Final transcriptionvoice-input
- User speaking detected
Assistant events
function-call
- Tool/function invokedassistant-message
- Assistant responseconversation-update
- Conversation state change
System events
error
- Error occurredrecording-ready
- Call recording availableanalysis-ready
- Call analysis complete
Advanced configuration
Headers and authentication
The listener adds helpful headers to forwarded requests:
Your server receives the exact webhook payload from Vapi with these additional headers for debugging.
Setting up with different tunneling services
Using ngrok
Using localtunnel
Using cloudflared
Pro tip: Some tunneling services offer static URLs (like ngrok with a paid plan), which means you won’t need to update your Vapi webhook configuration every time you restart development.
Filtering events
Filter specific event types (coming soon):
Response handling
The listener expects standard HTTP responses:
- 200-299: Success, event processed
- 400-499: Client error, event rejected
- 500-599: Server error, will retry
Development workflow
Typical setup
Data flow: Vapi sends webhooks → Ngrok tunnel (public URL) → vapi listen (port 4242) → Your local server (port 3000)
Example webhook handler
Testing scenarios
Simulating errors
Test error handling in your webhook:
Load testing
Test with multiple concurrent calls:
Debugging specific calls
Filter logs by call ID:
Security considerations
The vapi listen
command is designed for development only. In production, use proper webhook endpoints with authentication.
Best practices
- Never expose sensitive data in console logs
- Validate webhook signatures in production
- Use HTTPS for production endpoints
- Implement proper error handling
- Set up monitoring for production webhooks
Production webhook setup
For production, configure webhooks in the Vapi dashboard:
Troubleshooting
Connection refused
If you see “connection refused”:
- Verify your server is running on the specified port
- Check the endpoint path matches your route
- Ensure no firewall is blocking local connections
Timeout errors
For timeout issues:
- Check response time - Vapi expects < 10s response
- Avoid blocking operations in webhook handlers
- Use async processing for heavy operations
Missing events
If events aren’t appearing:
- Check CLI authentication -
vapi auth whoami
- Verify account access to the resources
- Ensure events are enabled in assistant config
SSL/TLS errors
For HTTPS endpoints:
Next steps
Now that you can test webhooks locally:
- Build webhook handlers: Learn about all webhook events
- Implement tools: Add custom functionality
- Set up production webhooks: Deploy to production
Pro tip: Keep vapi listen
running while developing - you’ll see all events in real-time and can iterate quickly on your webhook handlers without deployment delays!