retailPay, createQrOrder, linkPayCreate) provide immediate feedback, webhooks are the source of truth for payment outcomes.
This guide covers how to implement webhook endpoints, verify their authenticity, handle retries, and integrate webhook events into your order management logic.
Why Webhooks Are Required
Rebell uses webhooks to:- Deliver final payment results (SUCCESS / FAIL)
- Notify merchants about asynchronous status changes after PROCESSING
- Provide a reliable, push-based channel for transaction updates
- Network instability between merchant and Rebell
- User actions happening after the initial API call
- Risk checks that complete asynchronously
- Multi-step payment approval flows
Webhook Endpoint Requirements
Your backend must expose an HTTPS endpoint capable of: Example endpoint URLs:| Environment | URL |
|---|---|
| Sandbox | https://sandbox-merchant.com/rebell/webhook |
| Production | https://merchant.com/rebell/webhook |
Webhook Payload Structure
A typical payment webhook payload:Field Definitions
| Field | Description |
|---|---|
eventType | Type of event (e.g., PAYMENT_RESULT) |
paymentId | Rebell payment identifier |
paymentRequestId | Merchant’s original request/order ID |
paymentStatus | SUCCESS or FAIL |
paymentAmount | Payment amount and currency |
paymentTime | Timestamp of finalization (ISO 8601) |
failureReason | Reason for failure (if any) |
merchantData | Optional merchant-related fields (store, terminal, etc.) |
Webhook Signature Verification
Rebell signs webhook POST requests using RSA, similar to how merchants sign API requests.Request Headers
Webhook requests include:Request-TimeheaderSignatureheader- JSON body
Signature Header Format
Verification Steps
1
Extract Headers and Body
Extract from the incoming request:
Request-TimeheaderSignatureheader- Raw JSON body
2
Rebuild Signing String
Reconstruct the signing string (mirroring inbound API logic):Where:
HTTP_PATHis your webhook path (e.g.,/rebell/webhook)Request-Timeis the timestamp from the headerBODYis the raw JSON body
3
Verify Signature
Verify using Rebell’s public key:
- Algorithm:
SHA256withRSA - Use the correct Rebell public key for the
keyVersionspecified
4
Validate Timestamp
Reject if
Request-Time is older than a defined window (e.g., 10 minutes) to prevent replay attacks5
Process Webhook
Only after successful verification, process the webhook event
Signature Verification Example
Sequence Diagram
Idempotency & Repeated Deliveries
Webhooks are designed to be at-least-once delivery. This means the same event may be delivered multiple times.Suggested Approach
1
Look Up Payment
Find the payment by
paymentId or paymentRequestId2
Check Status
If status is already FINAL (SUCCESS or FAIL), log and return HTTP 200
3
Update and Process
If status is not final, update it and proceed with business logic
HTTP Response Rules
| Scenario | Response | Rebell Behavior |
|---|---|---|
| Successful processing | HTTP 200 OK | No retry |
| Temporary error (DB lock, transient) | HTTP 5xx | Will retry |
| Invalid signature | HTTP 400/401 | Will retry |
| Permanent error | HTTP 4xx | May retry |
Performance RequirementEnsure your webhook endpoint responds quickly (under 2 seconds). Defer heavy processing to async workers if necessary to avoid timeouts.
Retry Policy
Rebell will retry webhook deliveries when:- HTTP status is not 2xx
- Connection fails
- TLS error occurs
- Exponential backoff between retries
- Limited number of retries (e.g., over 24 hours)
- Retries stop once a 2xx response is received
Complete Webhook Handler Example
Security Best Practices
Handling Webhook Events
On SUCCESS
Payment completed successfullyActions to take:
- Mark order as PAID in your system
- Trigger order fulfillment
- Issue tickets/receipts
- Send confirmation notification to customer
- Update frontend/POS if applicable
On FAIL
UX & Operational Considerations
- Best Practices
- Monitoring
Treat webhook as final authority for payment resultUse webhooks to trigger:
- Order fulfillment
- Ticket issuing
- Receipt generation
- Notifications to customer
- Webhook is delayed
- Merchant needs active confirmation (e.g., POS timeout)
Testing Checklist
Test these scenarios in sandbox before going live:Troubleshooting
Not receiving webhooks
Not receiving webhooks
Possible causes:
- Webhook URL not configured in Rebell dashboard
- Firewall blocking Rebell IPs
- HTTPS certificate issues
- Wrong environment (sandbox vs production)
- Verify webhook URL in merchant dashboard
- Check firewall rules and allowlist Rebell IPs
- Ensure valid SSL certificate
- Confirm environment settings match
Signature verification failing
Signature verification failing
Possible causes:
- Using wrong Rebell public key
- Key version mismatch
- Body parsing modifying raw content
- Incorrect signing string reconstruction
- Verify you’re using the correct public key for the
keyVersion - Ensure you capture the raw request body before JSON parsing
- Double-check signing string format matches specification
Receiving duplicate webhooks
Receiving duplicate webhooks
This is expected behavior - webhooks are at-least-once delivery.Solutions:
- Implement idempotent handling
- Check payment status before processing
- Use database transactions for state changes
Webhooks timing out
Webhooks timing out
Possible causes:
- Heavy processing in webhook handler
- Database connection issues
- External service calls blocking response
- Defer heavy processing to async workers/queues
- Optimize database queries
- Return 200 quickly, process asynchronously