Retries & DLQ
Delivery retries, dead-letter queue, and re-enqueue.
payzum retries failed webhook deliveries automatically and surfaces undeliverable messages in a dead-letter queue (DLQ) accessible from the admin.
When IPNs fire
Payment IPNs are sent when an invoice transitions to any of these statuses:
partially_paidfinishedexpiredfailed
Retry policy
The retry policy differs by webhook type:
| | Payment IPN | Mass-payout webhook | |--|-------------|---------------------| | Max attempts | 5 | 5 | | Backoff | 30 s (fixed) | 60 s (fixed) | | Total budget | ~2 minutes | ~5 minutes | | Timeout per attempt | 10 s | 15 s |
Every delivery attempt — success or failure — is recorded with its attempt count, the HTTP status your endpoint returned, and your endpoint's response body. You can review this history for any invoice in your dashboard.
Retry vs. drop
| Your response | Behavior |
|---------------|----------|
| 2xx | Delivery acknowledged; no further attempts |
| 5xx | Treated as a transient error; delivery is retried |
| 4xx | Treated as a permanent failure; delivery is dropped immediately |
| Timeout / network error | Retried |
Return 5xx (for example 503 Service Unavailable) when your handler is temporarily unable to process a delivery. Returning 4xx permanently drops that delivery — it will not be retried even if the issue was on your side. Design your handler to be idempotent and deduplicate on payment_id + payment_status (payment IPNs) or eventId (mass-payout webhooks) so replays are safe.
Failed deliveries
After 5 failed attempts, payzum stops retrying and marks the delivery as failed. Failed deliveries are listed in your dashboard under the merchant's webhook (IPN) deliveries, each showing the attempt count, the last HTTP status, and the response body your endpoint returned — so you can diagnose why your handler rejected them.
Replaying a delivery
Once your endpoint is healthy again, you can replay a failed delivery from your dashboard. payzum re-attempts it as a fresh delivery.
Because a replay (or a normal retry) can cause the same event to arrive more than once, keep your handler idempotent — see the recommendations below.
Idempotency recommendations
Design your IPN handler to be idempotent. The same event may arrive more than once — either from retries or from a replay. Deduplicate on payment_id + payment_status for payment IPNs, and on eventId for mass-payout webhooks, before taking any action.
- Check whether the transition was already processed in your database before updating order state.
- Avoid charging customers or releasing goods based on the delivery count — rely on the payment status fields.
- For mass-payout handlers, store each processed
eventIdand skip duplicates.