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
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
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:
Expected Response:
- Your endpoint should return a 2xx HTTP status code (200, 201, 204)
- Response time should be under 30 seconds
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:
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
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:
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:
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
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
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:
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:
Pre-Deployment Checklist
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
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
- API Documentation: Reference the Webhook API Documentation