Skip to main content

Common Issues

This guide covers the most frequently encountered issues when working with webhooks and our monitoring tools.

Connection Issues​

"Unable to connect to webhook endpoint"​

Symptoms:

  • CLI shows connection refused errors
  • WebSocket connection fails
  • Dashboard shows endpoint as offline

Causes & Solutions:

Wrong Endpoint URL​

✗ Invalid endpoint URL format. Expected format: https://domain.com/hooks/endpoint-id

Solution: Ensure your URL follows the correct format:

  • ✅ https://hookvm.com/hooks/c2a996bf-4b85-43f9-a2f6-0dfa3a3b0326
  • ❌ https://hookvm.com/webhook/c2a996bf (wrong path)
  • ❌ http://hookvm.com/hooks/endpoint-id (missing HTTPS)

Network Connectivity​

Solution: Check your internet connection and firewall settings:

# Test basic connectivity
ping hookvm.com

# Test HTTPS connectivity
curl -I https://hookvm.com

Service Outage​

Solution: Check our status page or try again in a few minutes.

"WebSocket connection failed"​

Symptoms:

  • Connection initially works but then drops
  • Intermittent disconnections
  • Real-time updates stop working

Solutions:

Corporate Firewall/Proxy​

Many corporate networks block WebSocket connections.

Solution: Contact your IT team to allow:

  • WebSocket connections to *.yourservice.com
  • Ports 80 and 443 for WebSocket traffic

VPN Issues​

Some VPNs interfere with WebSocket connections.

Solution: Try disconnecting from VPN temporarily to test.

CLI Tool Issues​

"Command not found: webhook"​

Symptoms:

bash: webhook: command not found

Causes & Solutions:

Not Installed Globally​

Solution: Install the CLI globally:

npm install -g @hookvm/cli

PATH Issues​

Solution: Add npm global bin to your PATH:

# Check npm global bin location
npm config get prefix

# Add to your shell profile (~/.bashrc, ~/.zshrc)
export PATH="$(npm config get prefix)/bin:$PATH"

Permission Errors​

Solution: Fix npm permissions or use a Node version manager:

# Option 1: Fix npm permissions
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

# Option 2: Use nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install node
npm install -g @hookvm/cli

"Too many headers" Error​

Symptoms:

Request failed: too many headers

Cause: Some webhook sources send many headers, exceeding server limits.

Solution: This is automatically handled in newer versions. Update your CLI:

npm update -g @hookvm/cli

CLI Terminal UI Issues​

Broken Display​

Symptoms:

  • Garbled text in terminal UI
  • Missing characters or colors
  • Interface doesn't respond to keyboard input

Solutions:

  1. Check terminal compatibility:

    echo $TERM
    # Should show something like "xterm-256color"

  2. Use simple console mode:

    hookvm listen endpoint-url --disable-ui

  3. Update terminal:

    • macOS: Update Terminal.app or try iTerm2
    • Windows: Use Windows Terminal instead of Command Prompt
    • Linux: Try a different terminal emulator

Keyboard Shortcuts Don't Work​

Solution: Ensure your terminal supports the required key combinations:

  • Try using arrow keys instead of j/k
  • Use numbers (1-4) instead of tab navigation
  • Press 'q' to quit if other shortcuts fail

Forwarding Issues​

"Connection refused" for Local Forwarding​

Symptoms:

🔴 POST / [12:34:56] → ❌ Connection refused
└── 📤 Forwarded → localhost:3000 (❌ Connection refused)

Causes & Solutions:

Local Server Not Running​

Solution: Start your local development server:

# Check if anything is running on the port
lsof -i :3000

# Start your server
npm run dev  # or your start command

Wrong Port​

Solution: Verify which port your server is using:

# Your server logs should show something like:
# "Server running on http://localhost:3000"

# Use the correct port in CLI
hookvm listen endpoint-url --target http://localhost:3000/webhooks

Wrong Path​

Solution: Ensure your webhook handler exists at the specified path:

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

"404 Not Found" for Forwarded Requests​

Symptoms:

🟡 POST / [12:34:56] → 404 Not Found
└── 📤 Forwarded → localhost:3000 (🟡 404 Not Found)

Cause: Your local app doesn't have a handler at the specified path.

Solutions:

  1. Check your routes:

    // Make sure you have this route
    app.post('/webhooks', (req, res) => { /* handler */ });

  2. Verify the path in CLI:

    hookvm listen endpoint-url --target http://localhost:3000/api/webhooks
    #                                                      ^^^^^^^^^^^^
    #                                                   correct path

  3. Test route exists:

    curl http://localhost:3000/webhooks
    # Should not return 404

Web Interface Issues​

"Can't create endpoint"​

Symptoms:

  • Create endpoint button doesn't work
  • Form submission fails
  • Error messages about validation

Solutions:

Browser Issues​

  1. Clear browser cache and refresh
  2. Disable ad blockers temporarily
  3. Try incognito/private mode
  4. Use a different browser

Form Validation Errors​

Common validation issues:

  • Endpoint name must be unique in your organization
  • URL must be a valid HTTPS URL (if provided)
  • Description cannot be empty

Account Limits​

Check if you've reached your plan limits:

  • Free plan: Usually limited to 3-5 endpoints
  • Paid plans: Check your plan details in Settings

"Events not appearing"​

Symptoms:

  • Webhook sent but no event in dashboard
  • CLI shows events but web interface doesn't
  • Events appear with delay

Causes & Solutions:

Event Filtering​

Solution: Check your event filters in the dashboard:

  1. Navigate to Events page
  2. Clear any applied filters
  3. Refresh the page

Browser Caching​

Solution:

  • Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)
  • Clear browser cache for the site

Real-time Connection Issues​

Solution:

  • Refresh the page to re-establish WebSocket connection
  • Check browser console for WebSocket errors

Authentication Issues​

"Unauthorized" Errors​

Symptoms:

{
  "path": "/",
  "error": "Unauthorized",
  "message": "Authentication required to access this resource"
}

Cause: Using old endpoint URLs that require authentication.

Solution: Our service doesn't require authentication for basic webhook monitoring. If you're seeing this error:

  1. Verify endpoint URL is correct
  2. Check if you're using an old API that required auth
  3. Contact support if the error persists

"Invalid API Key"​

Symptoms: Getting API key validation errors

Solution: Our webhook monitoring service doesn't use API keys for basic functionality. You might be:

  • Using an outdated integration guide
  • Mixing up with another service's documentation
  • Using enterprise features that require authentication

Performance Issues​

Slow Event Processing​

Symptoms:

  • Events take long time to appear
  • Forwarding is slow
  • Interface is unresponsive

Solutions:

High Event Volume​

Solution: Use console mode for better performance:

hookvm listen endpoint-url --disable-ui --target your-handler-url

Network Latency​

Solution:

  • Check your internet connection speed
  • Try from a different network
  • Contact support if using enterprise deployment

Local Handler Performance​

Solution: Optimize your webhook handler:

  • Return responses quickly (< 30 seconds)
  • Process heavy work asynchronously
  • Add proper error handling

Getting Help​

Before Contacting Support​

  1. Check this troubleshooting guide
  2. Search our FAQ
  3. Try the basic solutions (restart, refresh, update)
  4. Gather error messages and screenshots

What to Include in Support Requests​

  • Exact error messages (copy and paste)
  • Steps to reproduce the issue
  • Your environment (OS, browser, CLI version)
  • Endpoint ID or configuration details
  • Screenshots if relevant

Contact Options​

  • Documentation: Check other sections of this guide
  • Community Forum: Ask questions and see solutions from other users
  • Email Support: For account and billing issues
  • Live Chat: Available during business hours for urgent issues

Still having issues? Check our debugging guide or contact support.