Troubleshooting Webhooks

Diagnose and resolve common webhook issues

When webhooks aren’t working as expected, systematic troubleshooting can help you quickly identify and resolve issues. This guide covers common problems, diagnostic techniques, and solutions for webhook integration issues.

Quick diagnosis checklist

Start with these basic checks to identify the most common issues:

Webhook not receiving events

Check these first:

• Webhook URL is correct and accessible
• Event types are properly subscribed
• Webhook is active (not paused)
• No firewall blocking Rise servers
• SSL certificate is valid (for HTTPS endpoints)

Signature verification failing

Common causes:

• Incorrect webhook secret
• Wrong signature parsing logic
• JSON stringification mismatch
• Character encoding problems

Slow or timeout responses

Performance issues:

• Database queries taking too long
• External API calls blocking
• Heavy processing in webhook handler
• Memory leaks causing slowdown
• Insufficient server resources

Inconsistent webhook delivery

Reliability problems:

• Network connectivity issues
• Load balancer misconfigurations
• Server restarts during processing
• Database connection pool exhaustion
• Race conditions in processing logic

Common error scenarios

HTTP status code errors

Different HTTP responses indicate different types of issues:

400 Bad Request

Common causes:

• Invalid signature verification
• Malformed JSON in response
• Missing required headers
• Request body parsing errors

Resolution: Check signature logic and request handling

401 Unauthorized

Common causes:

• Missing authentication headers
• Invalid API keys or tokens
• Expired authentication credentials

Resolution: Verify authentication configuration

404 Not Found

Common causes:

• Incorrect webhook URL path
• Server routing misconfiguration
• Application not running

Resolution: Verify URL and server configuration

500 Internal Server Error

Common causes:

• Unhandled exceptions in webhook code
• Database connection failures
• External service timeouts

Resolution: Check application logs and error handling

502 Bad Gateway

Common causes:

• Load balancer cannot reach backend
• Application server crashed
• Proxy configuration issues

Resolution: Check infrastructure and application health

503 Service Unavailable

Common causes:

• Server overloaded or maintenance
• Rate limiting triggered
• Circuit breaker activated

Resolution: Check server capacity and rate limits

Signature verification issues

Signature verification is the most common source of webhook problems:

Debug signature verification

Step-by-step debugging:

function debugSignatureVerification(payload, signature, secret) {
  console.log('Debugging signature verification:');
  console.log('Received signature:', signature);
  console.log('Webhook secret:', secret ? 'Present' : 'Missing');

  // Parse signature components
  const elements = signature.split(',');
  console.log('Signature elements:', elements);

  if (elements.length !== 2) {
    console.error('Invalid signature format - should have timestamp and hash');
    return false;
  }

  const timestamp = elements[0].split('=')[1];
  const receivedHash = elements[1].split('=')[1];

  console.log('Extracted timestamp:', timestamp);
  console.log('Extracted hash:', receivedHash);

  // Create signed payload
  const signedPayload = `${timestamp}.${JSON.stringify(payload)}`;
  console.log('Signed payload:', signedPayload);

  // Generate expected hash
  const expectedHash = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  console.log('Expected hash:', expectedHash);
  console.log('Received hash:', receivedHash);
  console.log('Hashes match:', expectedHash === receivedHash);

  return expectedHash === receivedHash;
}

Common signature mistakes

Mistake 1: Wrong JSON stringification

// Wrong - includes spaces
const signedPayload = `${timestamp}.${JSON.stringify(payload, null, 2)}`;

// Correct - compact format
const signedPayload = `${timestamp}.${JSON.stringify(payload)}`;

Mistake 2: Incorrect secret

// Wrong - using wrong secret
const secret = 'webhook-secret-key'; // Generic secret

// Correct - use exact secret from Rise webhook settings
const secret = process.env.RISE_WEBHOOK_SECRET; // From Rise dashboard

Mistake 3: Wrong header name

// Wrong - incorrect header case
const signature = req.headers['X-Rise-Signature'];

// Correct - lowercase header name
const signature = req.headers['x-rise-signature'];

Test signature generation

Create test signatures for debugging:

function generateTestSignature(payload, secret) {
  const timestamp = Math.floor(Date.now() / 1000);
  const signedPayload = `${timestamp}.${JSON.stringify(payload)}`;
  const hash = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  return `t=${timestamp},v1=${hash}`;
}

// Test with known payload
const testPayload = {
  id: 'we-test123',
  object: 'event',
  created: Math.floor(Date.now() / 1000),
  event_type: 'payment.sent',
  event_version: '1.0',
  payment: { nanoid: 'pa-test123' }
};

const testSignature = generateTestSignature(testPayload, 'your-secret');
console.log('Test signature:', testSignature);

// Verify it works with SDK
import { WebhookValidator } from '@riseworks/sdk';

const validator = new WebhookValidator({
  secret: 'your-secret',
  tolerance: 600
});

try {
  const event = validator.validateEvent(testPayload, testSignature);
  console.log('Verification result: Valid');
} catch (error) {
  console.log('Verification result: Invalid -', error.message);
}

What’s next?

After resolving webhook issues:

Monitoring Setup

Set up comprehensive monitoring to prevent future issues

Testing Guide

Implement thorough testing to catch issues early

Migration Guide

Learn about webhook version migrations and updates

Event Reference

Technical reference for webhook event types and payloads

Troubleshooting tip: Keep detailed logs during debugging, but remember to remove sensitive data before sharing logs with support or team members.