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

# Webhook Troubleshooting

> Diagnose and resolve common webhook issues.

## Webhook Not Receiving Events

### Symptoms

* No webhook events are being delivered to your endpoint
* Webhook appears configured correctly but no traffic is received
* Events are occurring but webhooks are not triggered

### Diagnostic Steps

<Steps>
  <Step title="Verify Webhook Configuration">
    **Check in Monitor:**

    * Navigate to Developer Tools > Webhooks
    * Verify the webhook status is "Enabled"
    * Confirm the endpoint URL is correct and accessible
    * Ensure you're subscribed to the correct event types

    **Verify Event Subscriptions:**

    * Confirm you're subscribed to the events you expect to receive
    * Check that the resources (persons, businesses, transfers, etc.) you're testing actually trigger the subscribed events
  </Step>

  <Step title="Test Endpoint Accessibility">
    **From Monitor:**

    * Use the built-in "Test Webhook" feature in the webhook configuration
    * This will send a test POST request to verify connectivity

    **Manual Testing:**

    ```bash theme={null}
    # Test if your endpoint is reachable
    curl -X POST https://your-webhook-endpoint.com/webhook \
      -H "Content-Type: application/json" \
      -d '{"test": "connectivity"}'
    ```

    **Expected Response:**

    * Your endpoint should return a 2xx HTTP status code (200, 201, 204)
    * Response time should be under 30 seconds
  </Step>

  <Step title="Check Firewall and Network Settings">
    **Verify Network Access:**

    * Ensure your endpoint is publicly accessible (not behind authentication)
    * Check that your server's firewall allows incoming connections from Orum's IP addresses
    * Verify any load balancers or proxies are correctly configured

    **Orum IP Addresses to Allowlist:**

    ```text theme={null}
    Sandbox: 34.232.246.7
    Production: 34.231.148.64, 3.234.102.51, 54.221.230.177
    ```
  </Step>
</Steps>

### Common Solutions

**Webhook Status Issues:**

* **Disabled Webhook**: Enable the webhook in Monitor
* **Error State**: Check delivery logs for specific error messages and resolve the underlying issue

**URL Configuration Issues:**

* **HTTP vs HTTPS**: Use HTTPS URLs for production webhooks
* **Incorrect Port**: Ensure your endpoint is accessible on the specified port
* **Path Issues**: Verify the full URL path is correct, including any query parameters

**Event Subscription Issues:**

* **Wrong Event Types**: Subscribe to the specific events you need (e.g., `transfer_updated` for transfer status changes)
* **Resource Lifecycle**: Understand which actions trigger events (e.g., creating a person triggers `person_created`)

## Signature Verification Failures

### Symptoms

* Webhook signature verification fails consistently
* "Invalid signature" errors in your webhook handler
* Uncertainty about whether webhooks are from Orum

### Diagnostic Steps

<Steps>
  <Step title="Verify Public Key">
    **Get Current Public Key:**

    * In Monitor, open the **"Webhook Secret"** modal
    * Copy the current public key
    * Ensure your server is using the exact same public key string

    **Check Key Format:**

    ```text theme={null}
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
    -----END PUBLIC KEY-----
    ```
  </Step>

  <Step title="Verify Signature Algorithm">
    **Correct Implementation:**

    * Use RSA-SHA256 signature verification
    * Concatenate: `request_body + created_at_timestamp`
    * Hash with SHA256
    * Verify with PKCS1 v1.5 padding
    * Decode signature from base64

    **Implementation Check:**

    ```python theme={null}
    # Python example - verify your implementation matches this pattern
    import base64
    from Crypto.PublicKey import RSA
    from Crypto.Hash import SHA256
    from Crypto.Signature import pkcs1_15

    # Concatenate body + timestamp (as string, not formatted)
    message_plus_created_at = request_body + created_at_string

    # Create hash
    encoded = message_plus_created_at.encode()
    result = SHA256.new(encoded)

    # Verify signature
    key = RSA.import_key(public_key_string)
    pkcs1_15.new(key).verify(result, base64.b64decode(signature))
    ```
  </Step>

  <Step title="Debug Signature Components">
    **Log Signature Components:**

    * Log the exact request body (as received, no modifications)
    * Log the `created_at` timestamp value
    * Log the concatenated string before hashing
    * Log the signature header value
    * Compare with test webhook signatures
  </Step>
</Steps>

### Common Solutions

**Public Key Issues:**

* **Wrong Key**: Ensure you're using the public key from the correct webhook configuration
* **Key Format**: Verify the key includes the BEGIN/END PUBLIC KEY headers

**Implementation Issues:**

* **Body Modification**: Use raw request body, don't parse and re-stringify JSON
* **Timestamp Format**: Use the exact `created_at` value as a string, not a formatted timestamp
* **Encoding**: Ensure proper UTF-8 encoding for string concatenation
* **Base64 Decoding**: Properly decode the signature from base64 before verification

## High Delivery Failure Rate

### Symptoms

* Intermittent webhook delivery
* Timeouts or server errors

### Diagnostic Steps

<Steps>
  <Step title="Check Server Performance">
    **Endpoint Performance:**

    * Ensure webhook processing completes within 30 seconds
    * Monitor server CPU and memory usage during webhook processing
    * Check if your endpoint is handling concurrent requests properly
    * Verify database connections and external API calls aren't causing delays
  </Step>

  <Step title="Validate Response Handling">
    **HTTP Response Requirements:**

    * Return 2xx status codes for successful processing
    * Return response within 30 seconds
    * Don't return 3xx redirects (webhooks won't follow redirects)
    * Provide meaningful error responses for debugging
  </Step>
</Steps>

### Common Solutions

**Performance Issues:**

* **Async Processing**: Process webhooks asynchronously to respond quickly
* **Queue System**: Use a message queue for time-consuming webhook processing
* **Resource Optimization**: Optimize database queries and external API calls
* **Scaling**: Scale your webhook processing infrastructure for high volume

**Error Handling:**

* **Proper Status Codes**: Return 2xx for success, 4xx for client errors, 5xx for server errors
* **Error Logging**: Log detailed error information for debugging
* **Graceful Degradation**: Handle partial failures gracefully
* **Idempotency**: Implement idempotent processing to handle retries safely

## Authentication and Authorization Issues

### Symptoms

* 401 Unauthorized errors in delivery logs
* 403 Forbidden errors
* Webhooks blocked by authentication middleware

### Solutions

**Remove Authentication Requirements:**

* Webhook endpoints should be publicly accessible
* Don't require API keys, tokens, or other authentication
* Use webhook signature verification instead of authentication

**Alternative Approaches:**

* **Dedicated Endpoint**: Create a separate endpoint specifically for webhooks
* **Path-Based Exclusion**: Exclude webhook URLs from authentication middleware
* **IP Allowlisting**: Use firewall rules to restrict access to Orum IPs only

## Testing and Validation

### Manual Testing Tools

**Monitor Test Feature:**

* Use the built-in test webhook functionality
* Send sample events to verify your endpoint works correctly
* Review test delivery results and error messages

**External Testing Tools:**

```bash theme={null}
# Test webhook endpoint manually
curl -X POST https://your-webhook-endpoint.com/webhook \
  -H "Content-Type: application/json" \
  -H "Signature: test-signature" \
  -d '{
    "event_id": "test-event-id",
    "event_type": "transfer_updated",
    "created_at": "2023-01-01T00:00:00.000Z",
    "event_data": {
      "transfer": {
        "id": "test-transfer-id",
        "status": "completed"
      }
    }
  }'
```

**Webhook Development Tools:**

* **ngrok**: Create public URLs for local development
* **RequestBin**: Capture and inspect webhook requests
* **Webhook.site**: Generate test webhook URLs

### Validation Checklist

Before deploying webhook configurations:

<Accordion title="Pre-Deployment Checklist">
  * Endpoint responds with 2xx status codes
  * Response time is under 30 seconds
  * Signature verification is implemented and tested
  * Idempotent processing is implemented
  * Error handling and logging are in place
  * Endpoint is accessible from Orum's IP addresses
  * SSL certificate is valid (for HTTPS endpoints)
  * Webhook configuration includes correct event types
  * Test webhooks are processed correctly
</Accordion>

## Get Additional Help

### Information to Gather

When contacting support, include:

* **Webhook Configuration**: Endpoint URL, subscribed event types, enabled features
* **Timeline**: When the issue started and frequency of occurrence
* **Testing Results**: Results from manual endpoint testing
* **Server Logs**: Relevant error messages from your server logs

<Info>
  Need extra help? Send a note to [service@orum.io](mailto:service@orum.io) with the above details.
</Info>

### Resources

* **API Documentation**: Reference the [Webhook API Documentation](/api-reference/webhooks/overview)