diff --git a/fern/cli/mcp-integration.mdx b/fern/cli/mcp-integration.mdx index 5896fa6ca..d5dd5ed22 100644 --- a/fern/cli/mcp-integration.mdx +++ b/fern/cli/mcp-integration.mdx @@ -383,11 +383,11 @@ This project uses Vapi MCP for enhanced IDE support: ## Next steps -With MCP configured: +Now that MCP is configured: -- **[Initialize a project](/cli/init):** Add Vapi to your codebase -- **[Test webhooks locally](/cli/webhook):** Debug without external tunnels -- **[Explore API Reference](/api-reference):** See what your IDE now knows +- **[Create assistants](/quickstart/phone):** Build your first voice AI +- **[Test webhooks locally](/cli/webhook):** Debug webhooks with tunneling services +- **[Manage resources](/cli/overview#common-commands):** Use CLI commands --- diff --git a/fern/cli/overview.mdx b/fern/cli/overview.mdx index 3307f3f0e..682850217 100644 --- a/fern/cli/overview.mdx +++ b/fern/cli/overview.mdx @@ -97,13 +97,15 @@ Your IDE's AI assistant (Cursor, Windsurf, VSCode) gains complete, accurate know Forward webhooks to your local server for debugging: ```bash +# Terminal 1: Create tunnel (e.g., with ngrok) +ngrok http 4242 + +# Terminal 2: Forward webhooks vapi listen --forward-to localhost:3000/webhook ``` -The CLI provides a public endpoint that forwards events to your local server. You'll need to update your webhook URLs in Vapi to point to this endpoint. - -Automatic webhook URL configuration (like Stripe CLI) is coming soon. For now, manually update your webhook URLs in the Vapi dashboard. +**Important:** `vapi listen` is a local forwarder only - it does NOT provide a public URL. You need a separate tunneling service (like ngrok) to expose the CLI's port to the internet. Update your webhook URLs in Vapi to use the tunnel's public URL. ### 🔐 Multi-account management @@ -241,7 +243,7 @@ Now that you have the Vapi CLI installed: - **[Initialize a project](/cli/init):** Add Vapi to your existing codebase - **[Set up MCP](/cli/mcp):** Enhance your IDE with Vapi intelligence -- **[Test webhooks locally](/cli/webhook):** Debug without external tunnels +- **[Test webhooks locally](/cli/webhook):** Debug webhooks with tunneling services - **[Manage authentication](/cli/auth):** Work with multiple accounts --- diff --git a/fern/cli/webhook-testing.mdx b/fern/cli/webhook-testing.mdx index 1a23492d6..a578b0c6a 100644 --- a/fern/cli/webhook-testing.mdx +++ b/fern/cli/webhook-testing.mdx @@ -6,60 +6,78 @@ slug: cli/webhook ## Overview -The `vapi listen` command provides a webhook forwarding service that receives events from Vapi and forwards them to your local development server. This helps you debug webhook integrations without deploying your code. +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 +- Set up local webhook forwarding with a tunneling service - Debug webhook events in real-time - Configure advanced forwarding options - Handle different webhook types - -**Note on tunneling:** Currently, `vapi listen` requires you to manually update your webhook URLs in Vapi. Automatic tunnel creation (like Stripe CLI) is coming in a future update. - + +**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 + + Use a tunneling service like ngrok to create a public URL: + ```bash + # Example with ngrok + ngrok http 4242 # 4242 is the default port for vapi listen + ``` + + Note the public URL provided by your tunneling service (e.g., `https://abc123.ngrok.io`) + + ```bash vapi listen --forward-to localhost:3000/webhook ``` - Note the public URL provided in the output (e.g., `https://webhook-proxy.vapi.ai/wh_abc123def456`) + This starts a local server on port 4242 that forwards to your application - Go to your Vapi Dashboard and update your webhook URLs to point to the URL from step 1: - - Assistant webhook URL - - Phone number webhook URL + Go to your Vapi Dashboard and update your webhook URLs to point to your tunnel URL: + - Assistant webhook URL: `https://abc123.ngrok.io` + - Phone number webhook URL: `https://abc123.ngrok.io` - Or any other webhook configuration - Trigger webhook events (make calls, etc.) and see them forwarded to your local server in real-time + Trigger webhook events (make calls, etc.) and see them forwarded through the tunnel to your local server ## How it works -**Current implementation:** The `vapi listen` command currently acts as a local webhook forwarder. Unlike tools like Stripe CLI, it doesn't yet create an automatic tunnel to update your Vapi webhook URLs. You'll need to manually configure your webhook URL in Vapi to point to the CLI's endpoint. +**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: -**Coming soon:** Automatic tunneling that updates your Vapi webhook configuration is planned for a future release. +1. Use a tunneling service (ngrok, localtunnel, etc.) to expose port 4242 to the internet +2. Configure your Vapi webhook URLs to point to the tunnel URL +3. The flow is: Vapi → Your tunnel URL → vapi listen (port 4242) → Your local server - - The CLI starts a webhook server on port 4242 (configurable) + + The CLI starts a webhook forwarder on port 4242 (configurable) + + + + Your tunneling service creates a public URL that routes to port 4242 - Update your Vapi webhook URL to point to the CLI's public endpoint (provided when you start the listener) + Update your Vapi webhook URL to point to the tunnel's public URL - All webhook events are forwarded to your specified local endpoint + Webhook events flow: Vapi → Tunnel → CLI forwarder → Your local endpoint @@ -88,6 +106,9 @@ Use a different port for the webhook listener: ```bash # Listen on port 8080 instead of default 4242 vapi listen --forward-to localhost:3000/webhook --port 8080 + +# Remember to update your tunnel to use port 8080 +ngrok http 8080 ``` ### Skip TLS verification @@ -110,20 +131,21 @@ When you run `vapi listen`, you'll see: $ vapi listen --forward-to localhost:3000/webhook 🎧 Vapi Webhook Listener -📡 Listening on: https://webhook-proxy.vapi.ai/wh_abc123def456 +📡 Listening on: http://localhost:4242 📍 Forwarding to: http://localhost:3000/webhook -⚠️ Please update your webhook URL in Vapi to: - https://webhook-proxy.vapi.ai/wh_abc123def456 +⚠️ To receive Vapi webhooks: + 1. Use a tunneling service (e.g., ngrok http 4242) + 2. Update your Vapi webhook URLs to the tunnel URL Waiting for webhook events... -[2024-01-15 10:30:45] POST /webhook +[2024-01-15 10:30:45] POST / Event: call-started Call ID: call_abc123def456 Status: 200 OK (45ms) -[2024-01-15 10:30:52] POST /webhook +[2024-01-15 10:30:52] POST / Event: speech-update Transcript: "Hello, how can I help you?" Status: 200 OK (12ms) @@ -167,23 +189,56 @@ The listener adds helpful headers to forwarded requests: ```http X-Forwarded-For: vapi-webhook-listener -X-Original-Host: vapi-webhooks.ngrok.io +X-Original-Host: X-Webhook-Event: call-started X-Webhook-Timestamp: 1705331445 ``` Your server receives the exact webhook payload from Vapi with these additional headers for debugging. -### Manual webhook configuration - -Since automatic tunneling isn't available yet, you'll need to: +### Setting up with different tunneling services -1. Start the webhook listener and note the public URL -2. Go to your Vapi Dashboard or use the API to update webhook URLs -3. Set the webhook URL to the one provided by `vapi listen` + + + ```bash + # Terminal 1: Start ngrok tunnel + ngrok http 4242 + + # Terminal 2: Start vapi listener + vapi listen --forward-to localhost:3000/webhook + + # Use the ngrok URL in Vapi Dashboard + ``` + + + + ```bash + # Terminal 1: Install and start localtunnel + npm install -g localtunnel + lt --port 4242 + + # Terminal 2: Start vapi listener + vapi listen --forward-to localhost:3000/webhook + + # Use the localtunnel URL in Vapi Dashboard + ``` + + + + ```bash + # Terminal 1: Start cloudflare tunnel + cloudflared tunnel --url http://localhost:4242 + + # Terminal 2: Start vapi listener + vapi listen --forward-to localhost:3000/webhook + + # Use the cloudflare URL in Vapi Dashboard + ``` + + -**Future enhancement:** We're working on automatic webhook URL updates, similar to how Stripe CLI works. This will eliminate the manual configuration step. +**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 @@ -218,22 +273,38 @@ The listener expects standard HTTP responses: ``` - + ```bash # In terminal 2 + ngrok http 4242 # Creates public URL for the CLI listener + # Note the public URL (e.g., https://abc123.ngrok.io) + ``` + + + + ```bash + # In terminal 3 vapi listen --forward-to localhost:3000/api/vapi/webhook ``` + + Update your Vapi webhook URLs to point to the ngrok URL from step 2 + + Use the Vapi dashboard or API to trigger webhooks - See events in both terminals and debug your handler + See events in the CLI terminal and debug your handler + +**Data flow:** Vapi sends webhooks → Ngrok tunnel (public URL) → vapi listen (port 4242) → Your local server (port 3000) + + ### Example webhook handler diff --git a/fern/debugging.mdx b/fern/debugging.mdx index 98c15b0de..8ac703a52 100644 --- a/fern/debugging.mdx +++ b/fern/debugging.mdx @@ -122,17 +122,19 @@ Navigate to `Observe > Webhook Logs` to: