Testing Webhooks Locally

Learn how to test webhook integrations on your local development environment using our CLI tool's forwarding capabilities.

Overview

Local webhook testing allows you to:

• Receive real webhooks on your local development server
• Debug webhook handlers in your IDE
• Test integrations before deploying to production
• Iterate quickly without deploying every change

Prerequisites

• Webhook endpoint created in your dashboard
• CLI tool installed (installation guide)
• Local development server running your webhook handler

Setup Process

1. Start Your Local Server

Make sure your local application is running and can handle webhook requests:

# Example for different frameworks
npm run dev        # Next.js/React
rails server       # Rails
python manage.py runserver  # Django
node server.js     # Node.js

Your local server should be listening on a port (e.g., http://localhost:3000).

2. Create a Webhook Handler

Ensure you have an endpoint that can receive POST requests:

Node.js/Express Example

app.post('/webhooks', (req, res) => {
  console.log('Webhook received:', req.body);
  
  // Process the webhook data
  const event = req.body;
  
  // Always respond with 200 OK
  res.status(200).send('OK');
});

Python/Flask Example

@app.route('/webhooks', methods=['POST'])
def handle_webhook():
    event = request.get_json()
    print(f"Webhook received: {event}")
    
    # Process the webhook data
    
    return '', 200

Next.js API Route Example

// pages/api/webhooks.js
export default function handler(req, res) {
  if (req.method === 'POST') {
    console.log('Webhook received:', req.body);
    
    // Process the webhook data
    const event = req.body;
    
    res.status(200).json({ received: true });
  } else {
    res.setHeader('Allow', ['POST']);
    res.status(405).end(`Method ${req.method} Not Allowed`);
  }
}

3. Start CLI with Forwarding

Connect to your webhook endpoint and forward events to your local server:

hookvm listen https://hookvm.com/hooks/your-endpoint-id \
  --target http://localhost:3000/webhooks

You should see output like:

📡 Monitoring: https://hookvm.com/hooks/your-endpoint-id
📋 Endpoint ID: your-endpoint-id
🎯 Target URL: http://localhost:3000/webhooks
✓ WebSocket connected to webhook events

🚀 Webhook monitor is now active!
   Endpoint: https://hookvm.com/hooks/your-endpoint-id
   Forwarding to: http://localhost:3000/webhooks

Testing Workflow

1. Send Test Events

Use your service's webhook testing feature or send manual test events:

From Your Service (e.g., Stripe)

1. Go to your service's webhook dashboard
2. Find your endpoint
3. Click "Send test event"
4. Select an event type and send

Manual Test with curl

curl -X POST https://hookvm.com/hooks/your-endpoint-id \
  -H "Content-Type: application/json" \
  -d '{
    "event": "test.payment",
    "amount": 2000,
    "currency": "usd"
  }'

2. Monitor in CLI

Watch the real-time event flow in your CLI:

🟢 POST / [12:34:56] → ✅ 200
├── 📥 Received (webhook-service)
└── 📤 Forwarded → localhost:3000 (✅ 200 OK)

3. Debug in Your IDE

• Set breakpoints in your webhook handler
• Inspect the webhook payload
• Step through your processing logic
• Test error scenarios

Advanced Forwarding

Multiple Handlers

Forward to different local endpoints based on event type:

# Terminal 1 - Payment events
hookvm listen https://hookvm.com/hooks/payment-endpoint \
  --target http://localhost:3000/webhooks/payments

# Terminal 2 - User events  
hookvm listen https://hookvm.com/hooks/user-endpoint \
  --target http://localhost:3000/webhooks/users

Custom Headers

Add authentication or custom headers to forwarded requests:

hookvm listen https://hookvm.com/hooks/your-endpoint-id \
  --target http://localhost:3000/webhooks \
  --header "Authorization: Bearer your-local-token" \
  --header "X-Environment: development"

HTTPS Local Server

If your local server uses HTTPS:

hookvm listen https://hookvm.com/hooks/your-endpoint-id \
  --target https://localhost:3443/webhooks

Debugging Common Issues

Local Server Not Responding

Symptoms: CLI shows "forwarding failed" or timeout errors

Solutions:

1. Check server is running: Verify your local server is running on the specified port
2. Test endpoint directly:

   curl -X POST http://localhost:3000/webhooks \
     -H "Content-Type: application/json" \
     -d '{"test": true}'

3. Check firewall: Ensure no firewall is blocking the connection

Wrong Handler Path

Symptoms: Getting 404 errors on forwarded requests

Solutions:

1. Verify the path: Make sure /webhooks (or your path) exists in your local app
2. Check routing: Ensure your routes accept POST requests
3. Test with browser: Visit http://localhost:3000/webhooks to see if the route exists

Handler Errors

Symptoms: CLI shows forwarding succeeded but handler has errors

Solutions:

1. Check application logs: Look for errors in your local server logs
2. Add error handling: Ensure your handler has proper error handling
3. Return proper status: Always return HTTP 200 for successful processing

Network Issues

Symptoms: Cannot connect to webhook endpoint

Solutions:

1. Check internet connection: Ensure you can reach the webhook service
2. Verify endpoint URL: Make sure the endpoint URL is correct
3. Check firewall: Ensure WebSocket connections are allowed

Best Practices

Development Workflow

1. Start local server first before starting CLI forwarding
2. Use consistent ports across your development team
3. Version control webhook handlers like any other code
4. Test error scenarios not just successful cases

Security Considerations

1. Use test endpoints for development, not production endpoints
2. Don't commit sensitive data received via webhooks
3. Implement signature verification even in development
4. Use HTTPS for production-like testing

Performance Testing

1. Test with high volume: Use tools to send multiple rapid webhooks
2. Monitor response times: Ensure handlers respond quickly (< 30s)
3. Test concurrent requests: Multiple webhooks arriving simultaneously
4. Handle backpressure: What happens when your handler is slow?

Integration Examples

E-commerce Order Processing

app.post('/webhooks/orders', (req, res) => {
  const order = req.body;
  
  switch(order.event) {
    case 'order.created':
      console.log(`New order: ${order.id}`);
      // Update inventory, send confirmation email
      break;
      
    case 'order.shipped':
      console.log(`Order shipped: ${order.id}`);
      // Send tracking info to customer
      break;
      
    case 'order.cancelled':
      console.log(`Order cancelled: ${order.id}`);
      // Restore inventory, process refund
      break;
  }
  
  res.status(200).send('OK');
});

Payment Processing

app.post('/webhooks/payments', (req, res) => {
  const payment = req.body;
  
  if (payment.event === 'payment.succeeded') {
    // Mark order as paid
    markOrderPaid(payment.order_id);
    
    // Send receipt email
    sendReceiptEmail(payment.customer_email, payment);
    
    // Update analytics
    trackPaymentSuccess(payment.amount);
  }
  
  res.status(200).send('OK');
});

Next Steps

Once you've tested locally:

1. Deploy to staging with real webhook endpoints
2. Set up monitoring for production webhook handling
3. Configure alerting for webhook failures
4. Document your integration for your team

---

Ready for production? Learn about webhook security and best practices.