Webhook Overview
Amwal uses secure HTTPS webhooks to notify your server in real time whenever payment events occur (such as order authorizations, installment plan approvals, refunds, or customer cancellations).
Webhook Lifecycle
Rendering diagram...
Error Handling & Retry Logic
Retry Mechanism
Amwal implements an automated retry policy to ensure reliable delivery of payment events even during temporary endpoint outages or network degradation:
- Max attempts: 5 retries
- Backoff: 2^attempt seconds exponential backoff
- Max delay: 1 hour
- Retry triggers: HTTP 5xx server errors, connection timeouts, and network reachability errors
- No retry: HTTP 4xx client errors (e.g.
400 Bad Request,401 Unauthorized,404 Not Found)
Delivery Schedule
When a retry trigger occurs, deliveries are rescheduled according to exponential backoff:
| Attempt | Delay | Total Elapsed Time |
|---|---|---|
| Initial | Immediate | 0 seconds |
| Retry 1 | 2 seconds | ~2 seconds |
| Retry 2 | 4 seconds | ~6 seconds |
| Retry 3 | 8 seconds | ~14 seconds |
| Retry 4 | 16 seconds | ~30 seconds |
| Retry 5 | 32 seconds (up to max delay 1 hr) | Final attempt |
Implementation Best Practices
- Acknowledge Fast with HTTP
200: Respond immediately with an HTTP200 OKupon receiving and validating the webhook signature. Offload heavy background jobs (such as email dispatch, inventory fulfillment, or accounting synchronization) to an asynchronous worker queue. - Handle Idempotency: Because webhooks may be retried or delivered at least once, ensure your webhook receiver checks if the
transaction_id(data.id) has already been processed before taking duplicate business actions. - Validate Cryptographic Signatures: Always verify the
X-Signatureheader using Amwal's public key before trusting payload contents. See Signature Verification. - Subscribe to Desired Events: Register your webhook endpoint and event types using the API or Merchant Portal. See Webhook Event Types.