Webhooks Architecture & Verification
rafiqPay uses webhooks to notify your application asynchronously when an event happens in your account. Webhooks matter most for payments that finish after the customer has left your page, such as bank transfers.
Signature Header Structure
Verifying Signatures
To protect against man-in-the-middle tampering and replay attacks, verify the HMAC-SHA256 signature using the endpoint’s signing secret (rp_sec_...), shown once when you add the endpoint.
# Compute the expected v1 signature for a saved delivery and compare it with the header
printf '%s.%s' "$T" "$RAW_BODY" | openssl dgst -sha256 -hmac "$RAFIQPAY_WEBHOOK_SECRET" -hexRetry Schedule (8 Attempts)
If your webhook endpoint returns a non-2xx HTTP status code, redirects, refuses the connection or does not answer within 10 seconds, rafiqPay attempts delivery up to 8 times over about 45 hours. Each wait below is counted from the attempt before it:
Operational Best Practices
1. Respond with 200 OK immediately
Acknowledge receipt immediately before executing complex downstream business logic (e.g. sending emails or PDF generation). Offload heavy work to background queues.
2. Handle duplicate events idempotently
Network glitches can cause rafiqPay to retry an event even if your server processed it. Always log the event id and ignore duplicates.