Webhooks Overview

Webhooks allow Amwal to notify your backend servers in real time whenever an asynchronous payment event occurs, such as order approval, installment tracker decisions, refund executions, or dispute status changes.

Supported Webhook Events

Event Type	Description	Trigger Condition
`order.created`	New order initiated	Customer starts checkout process
`order.success`	Payment successful	Payment confirmed and completed
`order.failed`	Payment failed	Payment declined, failed, or cancelled
`order.updated`	Order Refund	Contain the Bank gateway refund details (`refund_tracker`).
`installment.tracker.approved`	The installment is approved	Contain the Installment tracker object with its status `"A"`
`installment.tracker.rejected`	The installment is rejected	Contain the Installment tracker object with its status `"R"`
`order.disputed`	Chargeback dispute update	Contains `disputed_status` to identify the chargeback status: `PENDING`, `RESOLVED`, or `LOST`.
`payment_link.expired`	Payment link expired	The payment link reaches its configured expiration time.
`modal.closed`	Payment modal closed	The customer closes the payment modal.

For detailed JSON schemas and parameter definitions for each event, see Webhook Event Types.

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

Webhook Security & Headers

Incoming webhook requests from Amwal include essential security headers:

Header	Description
`X-Api-Key`	Your API key fingerprint to verify sender authenticity and match the registered public key.
`X-Signature`	Base64-encoded RSA-PSS with SHA-256 signature generated by Amwal.
`Content-Type`	Set to `application/json`.

Verifying Webhook Signatures

To ensure incoming webhook requests are genuine and have not been tampered with in transit, verify the X-Signature header using RSA-PSS SHA-256. See the complete verification tutorial and code examples in Webhook Signature Verification.