> ## Documentation Index
> Fetch the complete documentation index at: https://docs.riseworks.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<AccordionGroup>
  <Accordion title="Webhook not receiving events" icon="triangle-exclamation">
    **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)
  </Accordion>

  <Accordion title="Signature verification failing" icon="key">
    **Common causes:**

    * Incorrect webhook secret
    * Wrong signature parsing logic
    * JSON stringification mismatch
    * Character encoding problems
  </Accordion>

  <Accordion title="Slow or timeout responses" icon="clock">
    **Performance issues:**

    * Database queries taking too long
    * External API calls blocking
    * Heavy processing in webhook handler
    * Memory leaks causing slowdown
    * Insufficient server resources
  </Accordion>

  <Accordion title="Inconsistent webhook delivery" icon="shuffle">
    **Reliability problems:**

    * Network connectivity issues
    * Load balancer misconfigurations
    * Server restarts during processing
    * Database connection pool exhaustion
    * Race conditions in processing logic
  </Accordion>
</AccordionGroup>

## Common error scenarios

### HTTP status code errors

Different HTTP responses indicate different types of issues:

<CardGroup cols={2}>
  <Card title="400 Bad Request" icon="circle-exclamation">
    **Common causes:**

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

    **Resolution:** Check signature logic and request handling
  </Card>

  <Card title="401 Unauthorized" icon="lock">
    **Common causes:**

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

    **Resolution:** Verify authentication configuration
  </Card>

  <Card title="404 Not Found" icon="circle-question">
    **Common causes:**

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

    **Resolution:** Verify URL and server configuration
  </Card>

  <Card title="500 Internal Server Error" icon="server">
    **Common causes:**

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

    **Resolution:** Check application logs and error handling
  </Card>

  <Card title="502 Bad Gateway" icon="network-wired">
    **Common causes:**

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

    **Resolution:** Check infrastructure and application health
  </Card>

  <Card title="503 Service Unavailable" icon="triangle-exclamation">
    **Common causes:**

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

    **Resolution:** Check server capacity and rate limits
  </Card>
</CardGroup>

### Signature verification issues

Signature verification is the most common source of webhook problems:

<Tabs>
  <Tab title="Debug signature verification">
    **Step-by-step debugging:**

    ```javascript theme={null}
    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;
    }
    ```
  </Tab>

  <Tab title="Common signature mistakes">
    **Mistake 1: Wrong JSON stringification**

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

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

    **Mistake 2: Incorrect secret**

    ```javascript theme={null}
    // 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**

    ```javascript theme={null}
    // Wrong - incorrect header case
    const signature = req.headers['X-Rise-Signature'];

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

  <Tab title="Test signature generation">
    **Create test signatures for debugging:**

    ```javascript theme={null}
    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/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);
    }
    ```
  </Tab>
</Tabs>

## What's next?

After resolving webhook issues:

<CardGroup cols={2}>
  <Card title="Monitoring Setup" icon="chart-line" href="/webhooks/operations/monitoring">
    Set up comprehensive monitoring to prevent future issues
  </Card>

  <Card title="Testing Guide" icon="flask" href="/webhooks/implementation/testing">
    Implement thorough testing to catch issues early
  </Card>

  <Card title="Migration Guide" icon="arrow-right" href="/webhooks/reference/migration">
    Learn about webhook version migrations and updates
  </Card>

  <Card title="Event Reference" icon="book" href="/webhooks/implementation/event-types">
    Technical reference for webhook event types and payloads
  </Card>
</CardGroup>

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