Paystack webhooks in production: duplicates, retries and timeouts
This guide covers the problems Paystack webhooks cause in production and how to handle each one. What Paystack sends and how it's signed is on the Paystack webhooks overview, every event type is on Paystack webhook events, and signature verification code is on Verify Paystack webhooks.
A webhook is often your signal that money moved, so a missed or repeated event can mean an order that never ships or a customer credited twice.
At a glance
| Problem | What to do | With Event Gateway |
|---|---|---|
| Timeouts | Return a 200 OK as soon as you accept the event; process in a background job | Accepts the delivery at once, then queues it for your service |
| Duplicates | Check a transaction reference or resource ID before giving value | Drops repeats before they reach your handler |
| Retries | Watch for Failed events; resend them from the Dashboard or the API | Accepts deliveries while your service is down and replays them |
| Choosing events | Handle the events you need and acknowledge the rest | Filters and routes events by type |
| Testing | Forward test mode events to localhost | Forwards to localhost and replays past events |
| Other limits | Confirm transactions before giving value; protect your secret key | Logs every event and attempt, so you can trace what was delivered |
Paystack webhook timeouts and slow handlers
Return a 200 OK as soon as you accept the event, then do the work in the background.
Why it happens: Paystack's support documentation says a webhook may stay pending or fail if your server takes too long to respond. Handlers that write to a database, fulfil an order or call another API before responding are the ones at risk, especially during a traffic spike. The work may have finished, but the delivery still looks failed to Paystack, which sends it again. Any 2xx response counts as delivered.
Fix it in your handler:
- Verify the signature and return
200straight away. - Push the event onto a queue (SQS, RabbitMQ or Redis) and process it in a worker. See why to process webhooks asynchronously.
- Keep the request path free of calls to other services, including Paystack's own verify endpoint.
With Event Gateway: Hookdeck accepts each Paystack delivery immediately, then queues events and delivers them to your service at a rate it can handle, with its own retries. You set the delivery timeout per destination.
Duplicate Paystack webhooks
Paystack can send the same event more than once, particularly when retries occur. Check whether you've already processed an event before you give value.
Why it happens: A delivery your server handled but didn't acknowledge gets retried, and resending from the Dashboard or the API sends the event again. Paystack's documented examples carry no event ID to deduplicate on. The signature doesn't help either: x-paystack-signature covers only the body and has no timestamp, so a captured request still verifies if someone replays it.
Fix it in your handler:
- Build an idempotency key from
eventand the most specific ID the event has. Charges and transfers havedata.reference, refundsdata.transaction_, disputesreference data.id, invoicesdata.invoice_codeand subscriptionsdata.subscription_code. Theeventpart matters for refunds, whose transaction reference stays the same as the status changes. - Use a database table with a unique constraint on the key, and record it in the same transaction as the side effect.
- Treat
subscription.expiring_differently: itscards datais an array, so there's no single ID to use. - Make downstream effects such as fulfilment and ledger writes idempotent.
With Event Gateway: Hookdeck deduplicates events before they reach your endpoint, so repeats are filtered at the infrastructure level rather than in each handler.
Paystack webhook retries and resends
Paystack retries deliveries automatically and marks those it can't deliver as Failed. Resend them from the Dashboard or the API once you've fixed the cause.
Why it happens: A delivery fails if your server returns a non-2xx response, takes too long or blocks the request. While Paystack waits to try again, the event shows as Pending. Paystack's own Magento plugin describes a retry window of about 72 hours. The attempt schedule is in Paystack's webhooks guide.
Fix it in your handler:
- Watch delivery history under Developers > Webhooks on the new Paystack Dashboard, which shows the attempts, your response code and your response body. Test and live events are stored separately, so check the right mode.
- To list failures with the API, use
GET /integration/webhooks/events?status=Failed, and to find one by reference, useGET /integration/webhooks/events/lookup. Paystack's samples show astatusofFailedwith astatus_detailofretryingorfailed, so checkstatus_detailto see whether Paystack is still trying. - Fix the cause first, then resend one event from the Dashboard or several with
POST /integration/webhooks/events/resend. To resend everything that matches a filter, usePOST /integration/webhooks/events/resend-matching, which is rate limited. - Check your webhook URL before resending. A resend goes to the URL configured now, which may not be the one Paystack first sent the event to.
With Event Gateway: Hookdeck captures every Paystack delivery while your services are down, so Paystack's attempts succeed. Failed events can be retried automatically, manually or in bulk once you recover.
Choosing which Paystack events to handle
Handle the events your integration needs, and return a 200 for the rest so they aren't retried.
Why it matters: The events you receive depend on the Paystack products you use, and every extra one is a request your server has to accept, verify and discard. The full list, with sample payloads, is on Paystack webhook events.
Fix it in your handler:
- Dispatch on the
eventfield in the body, because there's no event header to read. - Use the webhook endpoints API to send chosen events to a named endpoint:
POST /integration/webhooks/endpointstakes a name, a URL and a list of events, andGET /integration/webhooks/events-cataloglists the names. These return a403for integrations without endpoint management. - For a payment flow, start with
charge.success. A subscription flow also needssubscription.create,invoice.updateandinvoice.payment_failed, and a payout flow needstransfer.success,transfer.failedandtransfer.reversed.
With Event Gateway: Hookdeck filters and routes events by type or any other property, so one Paystack webhook URL can feed several services.
Testing and debugging Paystack webhooks locally
Trigger events in test mode, and use a tunnel to receive them on your machine.
Why it's awkward: Your webhook URL has to be publicly reachable, and development machines sit behind NAT and firewalls. Test and live modes have separate URLs and separate secret keys, so a handler that works in one can fail in the other.
How to do it:
- Run a tunnel such as the Hookdeck CLI and set its URL as your test webhook URL:
hookdeck listen 3000 paystack --path /webhooks/paystack. - Or use Paystack's CLI.
webhook listentunnels test events through ngrok and overwrites the Test Webhook URL on your Dashboard, so set it back afterwards.webhook ping --domain livesends a samplecharge.successto your configured URL. - If you use the webhook endpoints API,
POST /integration/webhooks/endpoints/{code}/pingchecks that an endpoint responds. - Use the Dashboard's detail view to compare the payload Paystack sent with the response your server returned.
With Event Gateway: The Hookdeck CLI receives webhooks on your machine without a public server, and you can replay past events with one click.
Other Paystack webhook limits
Plan for a signing key shared with the API, for confirming transactions, and for network rules before they reach production.
Confirm the transaction before giving value. After verifying the signature, call GET /transaction/verify/{reference} from your background job, and compare the amount, currency and status with what you expected before you hand over goods.
A signing key shared with the API. x-paystack-signature is keyed with your secret key, which also authorizes API calls, so a leak does more than expose webhooks. If you generate a new key, Paystack lets you choose when the old one expires. Accept both until it does.
A newer signature header. Samples Paystack added to its docs code in November 2026 verify a Paystack-Signature header with a dedicated whsec_ secret. See Verify Paystack webhooks before you assume which header your deliveries carry.
IP allowlists and firewalls. Your webhook URL has to stay publicly reachable, and a firewall that blocks Paystack's requests shows up as Pending or Failed deliveries. Paystack's webhooks guide covers IP whitelisting as a second check alongside the signature. Paystack's Dashboard feature of the same name is different: it restricts which addresses can use your secret key, and doesn't affect incoming webhooks.
Amounts in the smallest unit. Amounts are in the currency's smallest unit, such as kobo for NGN, so divide before you compare them with a display price.
With Event Gateway: Hookdeck only passes verified events to your app, and its logs let you trace exactly what was delivered and when while you reconcile payments.
Keep a Paystack payment event from getting lost in an outage.
Hookdeck Event Gateway accepts every Paystack delivery, verifies its signature, queues events and retries to your service on your schedule.