Skip to main content

Connecting to Endpoints

Learn how to connect the hookVM CLI to your webhook endpoints for real-time monitoring and local development.

Overview​

The hookVM CLI connects to your webhook endpoints to provide:

  • Real-time monitoring of incoming webhook events
  • Local forwarding to development servers
  • Interactive debugging with detailed event inspection
  • Historical event replay for testing

Authentication & Setup​

1. Login to hookVM​

Before connecting to endpoints, authenticate with hookVM:

hookvm login

This will:

  • Open your browser for secure authentication
  • Save your authentication token locally
  • Configure CLI for your account

2. Verify Authentication​

Check your login status:

hookvm login status

Expected output:

🔐 Authentication Status

Server: https://hookvm.com  
Status: Authenticated
User: John Doe (john@example.com)
Token: Valid

Endpoint Types & URLs​

Private Endpoints​

URL Format: https://hookvm.com/hooks/{endpoint-id}

Authentication: Required - you must be logged in and have access to the endpoint

Use Cases:

  • Production webhook monitoring
  • Secure development environments
  • Team collaboration

Example:

hookvm listen https://hookvm.com/hooks/abc123-def456-ghi789

Public Endpoints​

URL Format: https://hookvm.com/hooks/public/{endpoint-id}

Authentication: Not required - anyone with the URL can monitor

Use Cases:

  • Testing and demonstrations
  • Sharing webhook events with external teams
  • Public API integrations

Example:

hookvm listen https://hookvm.com/hooks/public/test-webhook-123

Basic Connection​

Monitor Webhook Events​

Connect to an endpoint to view incoming events in real-time:

hookvm listen https://hookvm.com/hooks/your-endpoint-id

What happens:

  1. CLI establishes WebSocket connection to hookVM
  2. Real-time events are displayed in interactive terminal UI
  3. Event details shown including headers, payload, and metadata
  4. Connection maintained until you press 'q' to quit

Console Output Mode​

For simpler output without interactive UI:

hookvm listen https://hookvm.com/hooks/your-endpoint-id --disable-ui

Benefits:

  • Easier to pipe output to files or other tools
  • Works better in CI/CD environments
  • Less resource intensive

Local Development Integration​

Forward Events to Local Server​

Forward webhook events to your local development server:

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

How it works:

  1. CLI receives webhook event from hookVM
  2. Event is forwarded to your local server at specified URL
  3. Response from local server is shown in CLI
  4. Original webhook source gets success response from hookVM

Custom Forward Path​

Forward to a specific path on your local server:

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

Multiple Local Environments​

Development Server:

hookvm listen https://hookvm.com/hooks/dev-endpoint --target http://localhost:3000/webhooks

Staging Server:

hookvm listen https://hookvm.com/hooks/staging-endpoint --target http://localhost:4000/api/v1/webhooks

Connection Success Output​

When connected successfully, you'll see:

📡 Monitoring: https://hookvm.com/hooks/your-endpoint-id
📋 Endpoint ID: abc123-def456-ghi789
🔌 WebSocket URL: wss://hookvm.com/ws
✓ WebSocket connected to webhook events

🚀 Webhook monitor is now active!
   Endpoint: https://hookvm.com/hooks/your-endpoint-id
   
📺 Interactive mode enabled. Press 'h' for help or 'q' to quit.

With forwarding enabled:

📡 Monitoring: https://hookvm.com/hooks/your-endpoint-id
🎯 Target URL: http://localhost:3000
✓ Connected (Monitoring + Forwarding)

Interactive Terminal UI​

When connected with interactive UI enabled:

Keyboard Shortcuts:

  • ↑/↓ or j/k - Navigate webhook list
  • Tab - Switch between panels (events, details, forwarding status)
  • Enter - View detailed event information
  • c - Clear all events from display
  • h - Show help screen
  • q - Quit and disconnect

Event Information Display​

Event List Panel:

  • Timestamp of each webhook event
  • HTTP method (POST, PUT, GET, etc.)
  • Source IP address of sender
  • Success/failure status
  • Forwarding status (if enabled)

Event Details Panel:

  • Complete HTTP headers
  • Raw request payload (formatted JSON/XML)
  • Query parameters
  • Response codes and timing

Forwarding Status Panel:

  • Target URL configuration
  • Forward success/failure rate
  • Response times from target server
  • Error messages for failed forwards

Finding Your Endpoint URL​

From hookVM Dashboard​

  1. Sign in to hookvm.com/dashboard
  2. Navigate to Endpoints
  3. Click on your endpoint
  4. Copy the Endpoint URL from the details page

From CLI After Creation​

When you create endpoints via CLI (future feature):

hookvm create-endpoint "My Test Endpoint"
# Output includes endpoint URL for CLI connection

Connection Troubleshooting​

Authentication Errors​

Error Message:

❌ Authentication failed
Please run "hookvm login" to authenticate with hookVM

Solutions:

# Re-authenticate
hookvm login

# Check authentication status
hookvm login status

# If token expired, logout and login again
hookvm logout
hookvm login

Invalid Endpoint URL Format​

Error Message:

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

Solutions:

  • Verify URL format matches exactly: https://hookvm.com/hooks/endpoint-id
  • Ensure no extra slashes or characters
  • Copy URL directly from dashboard to avoid typos

Valid Examples:

# Private endpoint ✅
hookvm listen https://hookvm.com/hooks/abc123-def456-ghi789

# Public endpoint ✅
hookvm listen https://hookvm.com/hooks/public/test-webhook-123

Invalid Examples:

# Missing /hooks/ path ❌
hookvm listen https://hookvm.com/abc123-def456-ghi789

# Wrong domain ❌
hookvm listen https://api.hookvm.com/hooks/endpoint-id

# Extra trailing slash ❌
hookvm listen https://hookvm.com/hooks/endpoint-id/

Network Connectivity Issues​

Error Message:

✗ Unable to connect to webhook endpoint
Make sure the endpoint URL is correct and the service is running

Solutions:

  1. Check Internet Connection:

    # Test basic connectivity to hookVM
    curl -I https://hookvm.com

  2. Verify Endpoint Accessibility:

    # Test if endpoint URL responds
    curl -I https://hookvm.com/hooks/your-endpoint-id

  3. Test with Public Endpoint:

    # Try a public endpoint to isolate authentication issues
    hookvm listen https://hookvm.com/hooks/public/test-endpoint

  4. Check Firewall Settings:

    • Ensure WebSocket connections (port 443) are allowed
    • Test from different network if corporate firewall blocks WebSockets

WebSocket Connection Problems​

Error Message:

✗ WebSocket connection failed: [error details]

Solutions:

Corporate Network Issues:

  • Configure proxy settings if needed: 
    export HTTPS_PROXY=http://proxy.company.com:8080
    hookvm listen https://hookvm.com/hooks/your-endpoint-id

Debug WebSocket Connection:

# Enable debug mode for detailed connection logs
DEBUG=hookvm* hookvm listen https://hookvm.com/hooks/your-endpoint-id

Test WebSocket Support:

  • Try from personal device/network to verify network support
  • Check if corporate firewall blocks WebSocket upgrades

Advanced Connection Options​

Environment Variables​

Configure CLI behavior with environment variables:

# Set connection timeout (seconds)
export HOOKVM_TIMEOUT=60

# Enable auto-reconnect
export HOOKVM_RECONNECT=true

# Set debug level
export DEBUG=hookvm*

# Use proxy
export HTTPS_PROXY=http://proxy.company.com:8080

Custom Server Configuration​

For enterprise deployments:

# Login to custom server
hookvm login --server https://your-hookvm.company.com

# Connect to endpoint on custom server
hookvm listen https://your-hookvm.company.com/hooks/endpoint-id

Batch Processing Mode​

For automated monitoring without interactive UI:

# Log events to file
hookvm listen https://hookvm.com/hooks/endpoint-id --disable-ui > webhook-events.log

# Limit number of events to capture
hookvm listen https://hookvm.com/hooks/endpoint-id --disable-ui --max-events 100

# JSON output for processing
hookvm listen https://hookvm.com/hooks/endpoint-id --disable-ui --format json

Performance Optimization​

Connection Efficiency​

Reduce Memory Usage:

# Limit displayed events in UI to prevent memory issues
hookvm listen https://hookvm.com/hooks/endpoint-id --max-events 50

Optimize for Long-Running Sessions:

# Enable connection keep-alive
HOOKVM_KEEPALIVE=true hookvm listen https://hookvm.com/hooks/endpoint-id

Local Forwarding Performance​

Ensure Fast Local Response:

  • Your local server should respond within 5 seconds
  • Implement async processing for heavy operations
  • Use appropriate timeout settings

Monitor Forwarding Health:

  • Watch forwarding status panel for failures
  • Check local server logs for processing errors
  • Verify target URL accessibility

Multi-Endpoint Monitoring​

Sequential Monitoring​

Monitor different endpoints one at a time:

# Monitor production endpoint
hookvm listen https://hookvm.com/hooks/prod-endpoint-123

# Stop with 'q', then switch to staging
hookvm listen https://hookvm.com/hooks/staging-endpoint-456

Parallel Monitoring​

Use multiple terminal sessions for simultaneous monitoring:

Terminal 1 - Production:

hookvm listen https://hookvm.com/hooks/prod-endpoint

Terminal 2 - Development:

hookvm listen https://hookvm.com/hooks/dev-endpoint --target http://localhost:3000

Terminal 3 - Testing:

hookvm listen https://hookvm.com/hooks/public/test-endpoint --disable-ui

Automated Monitoring Scripts​

Bash script for background monitoring:

#!/bin/bash
# monitor-webhooks.sh

echo "Starting hookVM monitoring..."

# Production monitoring (background)
hookvm listen https://hookvm.com/hooks/prod-endpoint --disable-ui > prod.log &
PROD_PID=$!

# Staging monitoring (background)
hookvm listen https://hookvm.com/hooks/staging-endpoint --disable-ui > staging.log &
STAGING_PID=$!

echo "Production monitoring (PID: $PROD_PID) -> prod.log"
echo "Staging monitoring (PID: $STAGING_PID) -> staging.log"
echo "Press Ctrl+C to stop"

# Graceful shutdown on interrupt
trap 'echo "Stopping monitors..."; kill $PROD_PID $STAGING_PID; exit' INT
wait

Integration with Development Workflow​

Local Development Setup​

1. Start Local Development Server:

# Node.js/Express example
npm run dev
# Server running on http://localhost:3000

2. Connect CLI with Forwarding:

hookvm listen https://hookvm.com/hooks/dev-endpoint --target http://localhost:3000/webhooks

3. Test Integration:

  • Send test webhooks from external service
  • Monitor events in CLI
  • Verify local server receives and processes events
  • Debug any issues using event details panel

CI/CD Integration​

Automated Testing in CI Pipeline:

# GitHub Actions example
- name: Test Webhook Integration
  run: |
    # Start webhook monitoring in background
    hookvm listen https://hookvm.com/hooks/test-endpoint --disable-ui --max-events 5 > webhook-test.log &
    MONITOR_PID=$!
    
    # Run integration tests
    npm test
    
    # Stop monitoring
    kill $MONITOR_PID
    
    # Analyze webhook logs
    grep "success" webhook-test.log

Security Best Practices​

Endpoint URL Protection​

Private Endpoints:

  • Never share private endpoint URLs in public repositories
  • Use environment variables for endpoint URLs in scripts
  • Rotate endpoint IDs regularly for sensitive integrations

Local Development:

  • Use dedicated development endpoints
  • Don't expose local development servers to public internet
  • Implement proper authentication in local webhook handlers

Network Security​

Corporate Networks:

  • Work with IT to ensure WebSocket connectivity
  • Use secure proxy configurations when required
  • Monitor for unauthorized access attempts

Local Development:

  • Bind local servers to localhost only unless needed
  • Use HTTPS for local development when possible
  • Validate all incoming webhook data

Next Steps​