Webhook Troubleshooting

​

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

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

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

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END PUBLIC KEY-----

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

​

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

​

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

​

Resources

• API Documentation: Reference the Webhook API Documentation