Overview
Setting up webhooks involves two main steps: implementing a webhook endpoint on your server and registering it with Modulus Labs. This guide walks you through the complete setup process.1
Implement Webhook Endpoint
Create a POST endpoint on your server that can receive and process webhook notifications
2
Register with Modulus Labs
Use the Create Webhook API to register your endpoint URL
3
Test Your Integration
Use the Simulate API to verify your webhook handler works correctly
4
Go Live
Enable your webhook and start receiving real transaction notifications
Prerequisites
Before registering a webhook, ensure you have:Publicly Accessible Endpoint
Your webhook URL must be accessible from the internet (not localhost)
HTTPS Support
Webhook URLs must use HTTPS for security (HTTP not supported in production)
Secret Key
Your Modulus Labs secret key for API authentication and JWE decryption
Fast Response Time
Endpoint must respond within 10 seconds to avoid timeouts
Step 1: Implement Your Webhook Endpoint
Create a POST endpoint on your server that accepts webhook notifications.Basic Webhook Handler Structure
Webhook Handler Requirements
Accept POST Requests
Accept POST Requests
Your endpoint must accept POST requests with
Content-Type: application/json.Respond Quickly
Respond Quickly
Return
200 OK within 10 seconds. Process webhook data asynchronously if needed:Decrypt JWE Payload
Decrypt JWE Payload
All webhook payloads are encrypted with JWE. You must decrypt them using your secret key before processing.See Payload Documentation for detailed decryption instructions.
Handle Retries Idempotently
Handle Retries Idempotently
Modulus Labs retries failed webhooks up to 4 times. Use
referenceNumber to prevent duplicate processing:Log All Webhooks
Log All Webhooks
Log every webhook receipt for debugging and audit purposes:
Step 2: Register Your Webhook
Use the Create Webhook API to register your endpoint with Modulus Labs.Create Webhook Request
Configuration Options
The HTTPS URL where Modulus Labs will send webhook notifications. Must be publicly accessible.Example:
"https://api.yourcompany.com/webhooks/modulus"Array of webhook actions you want to receive. Options:
QRPH_SUCCESS, QRPH_DECLINED, or both.Example: ["QRPH_SUCCESS", "QRPH_DECLINED"]Webhook status:
ENABLED or DISABLED.Example: "ENABLED"Use DISABLED if you want to register the webhook but not receive notifications yet (useful during development).Response
Save the webhook
id returned in the response. You’ll need it to update or delete the webhook later.Step 3: Test Your Webhook
Use the Simulate API to send test webhooks to your endpoint without creating real transactions.Simulate Successful Payment
Simulate Declined Payment
Simulate API Reference
Complete documentation for testing webhooks in sandbox
Managing Webhooks
View All Webhooks
Check your registered webhooks:Update Webhook
Change webhook URL or actions:Disable Webhook
Temporarily stop receiving webhooks:Delete Webhook
Permanently remove a webhook:Multi-Merchant Support
If you manage multiple merchants, use theactivation-code header to identify which merchant account a webhook belongs to.
Set Activation Code on Webhook Creation
Receive Activation Code in Webhooks
Modulus Labs includes theactivation-code in webhook requests:
Best Practices
Use HTTPS
Always use HTTPS URLs for webhooks in production. HTTP is not secure and may be rejected.
Unique URLs per Environment
Use different webhook URLs for sandbox and production to avoid mixing test and live data.
Monitor Webhook Health
Set up monitoring alerts if your webhook endpoint becomes unreachable or starts failing.
Version Your Webhook Endpoint
Include API version in webhook URL path (e.g.,
/v1/webhooks/modulus) to allow gradual migrations.Implement Replay Protection
Use
referenceNumber and timestamps to detect and ignore duplicate or replayed webhooks.Graceful Error Handling
Return 2xx for successfully received webhooks, even if business logic fails. Log errors for later resolution.
Troubleshooting
Webhook Not Receiving Notifications
Webhook Not Receiving Notifications
Possible causes:
- Webhook URL is not publicly accessible
- Firewall blocking incoming requests
- Webhook status is DISABLED
- HTTPS certificate issues
- Test URL accessibility from external network
- Verify webhook status is ENABLED using GET /v1/webhooks
- Check server logs for incoming requests
- Use Simulate API to send test webhook
Decryption Failures
Decryption Failures
Possible causes:
- Using wrong secret key
- JWE library not configured correctly
- Payload corrupted during transmission
- Verify secret key matches the one used to create QR codes
- Log raw webhook payload for inspection
- Test decryption with Simulate API first
- Check JWE library documentation for your language
Webhook Timeouts
Webhook Timeouts
Possible causes:
- Endpoint takes longer than 10 seconds to respond
- Blocking operations in webhook handler
- Database queries timing out
- Return 200 OK immediately, process asynchronously
- Move heavy operations to background jobs
- Add request timeout logging
- Use caching for frequently accessed data
Duplicate Webhooks
Duplicate Webhooks
Possible causes:
- Webhook retry mechanism (expected behavior)
- Network issues causing Modulus Labs to resend
- Endpoint returning non-200 status codes
- Implement idempotency using referenceNumber
- Check if webhook was already processed before handling
- Ensure endpoint returns 200 OK for successful receipts
- Log webhook IDs to track duplicates
Security Checklist
1
Use HTTPS
- Webhook URL uses HTTPS (not HTTP)
- SSL certificate is valid and not expired
2
Verify Webhook Authenticity
- Decrypt JWE payload successfully
- Validate payload structure matches expected format
- Check referenceNumber exists in your system
3
Protect Against Replay Attacks
- Track processed referenceNumbers
- Reject duplicate webhook deliveries
- Validate webhook timestamps are recent
4
Secure Your Endpoint
- Endpoint doesn’t expose sensitive debugging info
- Rate limiting configured to prevent abuse
- Error messages don’t leak system details
5
Monitor and Alert
- Failed webhook processing triggers alerts
- Unusual webhook patterns detected
- Decryption failures logged and monitored