Skip to main content

Debugging Webhooks

Comprehensive debugging guide for webhook integrations, including tools, techniques, and common troubleshooting scenarios.

Debug Tools​

CLI Debugging​

# Enable debug logging
WEBHOOK_CLI_LOG_LEVEL=debug hookvm listen endpoint-url

# Log to file
hookvm listen endpoint-url --disable-ui > debug.log 2>&1

# Verbose network debugging
WEBHOOK_CLI_DEBUG=network hookvm listen endpoint-url

Browser Developer Tools​

  1. Open DevTools (F12)
  2. Go to Network tab
  3. Monitor WebSocket connections
  4. Check for error messages

Handler Debugging​

Add Debug Logging​

app.post('/webhooks', (req, res) => {
  console.log('=== WEBHOOK DEBUG ===');
  console.log('Headers:', JSON.stringify(req.headers, null, 2));
  console.log('Body:', JSON.stringify(req.body, null, 2));
  console.log('Method:', req.method);
  console.log('URL:', req.url);
  console.log('====================');
  
  // Process webhook
  
  res.status(200).json({ 
    received: true,
    debug: true,
    timestamp: new Date().toISOString()
  });
});

Use Debugger​

app.post('/webhooks', (req, res) => {
  debugger; // Breakpoint for debugging
  
  const event = req.body;
  // Step through processing logic
  
  res.status(200).json({ received: true });
});

Common Debug Scenarios​

Events Not Appearing​

Check Filters​

  1. Dashboard filters - Clear all event filters
  2. Time range - Expand to "All time"
  3. Endpoint selection - Ensure correct endpoint selected

Verify Configuration​

# Test endpoint directly
curl -X POST https://hookvm.com/hooks/your-endpoint-id \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

Handler Not Called​

Check Route Configuration​

// Make sure route exists and accepts POST
app.post('/webhooks', handler); // ✅ Good
app.get('/webhooks', handler);  // ❌ Wrong method
app.post('/webhook', handler);  // ❌ Wrong path

Test Handler Directly​

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

Signature Verification Issues​

Debug Signature Calculation​

function debugSignature(payload, signature, secret) {
  console.log('Payload:', payload);
  console.log('Received signature:', signature);
  console.log('Secret:', secret);
  
  const calculated = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
    
  console.log('Calculated signature:', calculated);
  console.log('Signatures match:', calculated === signature);
  
  return calculated === signature;
}

Performance Debugging​

Response Time Analysis​

app.post('/webhooks', async (req, res) => {
  const startTime = Date.now();
  
  try {
    await processWebhook(req.body);
    const processingTime = Date.now() - startTime;
    
    console.log(`Processing took ${processingTime}ms`);
    res.status(200).json({ 
      success: true,
      processingTime 
    });
  } catch (error) {
    const errorTime = Date.now() - startTime;
    console.log(`Error after ${errorTime}ms:`, error);
    res.status(500).json({ error: 'Processing failed' });
  }
});

Memory Usage Monitoring​

app.post('/webhooks', (req, res) => {
  const memBefore = process.memoryUsage();
  
  processWebhook(req.body);
  
  const memAfter = process.memoryUsage();
  console.log('Memory usage:', {
    heapUsed: memAfter.heapUsed - memBefore.heapUsed,
    external: memAfter.external - memBefore.external
  });
  
  res.status(200).json({ received: true });
});

This section is under development. More debugging techniques and tools coming soon.