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

1

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
2

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

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:
Sandbox: 34.232.246.7
Production: 34.231.148.64, 3.234.102.51, 54.221.230.177

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

1

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:
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END PUBLIC KEY-----
2

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 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))
3

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

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

1

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
2

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

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

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
Need extra help? Send a note to [email protected] with the above details.

Resources