Troubleshooting Webhook Delivery & Timeout Failures

When an installment payment link is paid or a refund is processed, Amwal sends an HTTP POST event to your configured Webhook URL. If your server is not receiving events, use the troubleshooting steps below.

Webhook Delivery Lifecycle & Retry Policy

Amwal Gateway enforces an exponential backoff retry policy for endpoints that fail or time out:

Common Root Causes & Resolutions

1. Endpoint Timeout (> 5,000ms)

• Symptom: Amwal records an ETIMEDOUT or HTTP 504 status for your webhook endpoint.
• Root Cause: Your server performs synchronous, heavy database transactions or 3rd-party ERP calls before returning an HTTP response to Amwal.
• Resolution:
  • Immediately respond with HTTP 200 OK upon receiving and verifying the webhook signature.
  • Offload order fulfillment, inventory adjustments, and email notifications to an asynchronous background job queue (e.g. BullMQ, Celery, Laravel Queue).

2. Invalid or Self-Signed SSL Certificate

• Symptom: Webhook status displays SSL_CERT_UNTRUSTED.
• Root Cause: Amwal's security layer requires valid, trusted SSL/TLS certificates (Let's Encrypt, Cloudflare, DigiCert) and rejects self-signed certificates or expired intermediate chains.
• Resolution:
  • Test your SSL health using SSL Labs. Ensure TLS 1.2 or TLS 1.3 is enabled.

3. Firewall or Cloudflare Blocking Amwal IPs

• Symptom: Amwal receives HTTP 403 Forbidden from Cloudflare or AWS WAF.
• Root Cause: Web Application Firewall (WAF) bot-management rules flag incoming server-to-server POST requests without browser cookies.
• Resolution:
  • Whitelist Amwal Gateway IP ranges in your Cloudflare / AWS WAF security rules.
  • Exclude /webhook/amwal from CSRF token verification in frameworks like Laravel, Django, or Rails.

4. Receiving the Same Event Twice

• Symptom: Your handler processes what looks like the same order.success or order.updated event, twice, with identical payloads and no failure or timeout in between.
• Root Cause: Confirmed live — webhook delivery is at-least-once, not exactly-once. A successful delivery can still be sent twice, independent of the retry-on-failure policy above.
• Resolution:
  • Make your webhook handler idempotent. The payload doesn't include a dedicated delivery id — the most reliable dedupe key available is a combination of the transaction id and the event's status field, though this is imperfect for events whose payload doesn't change between deliveries (like order.success).
  • Also note: setting callback_url alone on a payment link does not deliver anything at all — confirmed live, no webhook and no browser redirect either, until a webhook endpoint is separately registered first via the (currently undocumented in api-reference) API. This page should eventually link to that setup step once it's published — for now, see the pipeline's reports/live-findings.md for the full writeup.

Viewing Webhook Logs in Merchant Portal

1. Log in to Amwal Merchant Portal.
2. Go to Developers -> Webhook Endpoints.
3. Click on your endpoint to open the Delivery Log.
4. Inspect the exact HTTP status code, request payload, response body, and retry history.
5. Click "Re-send Event" to manually trigger immediate delivery during testing.