Paystack webhooks in production: duplicates, retries and timeouts

Published · Updated

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

ProblemWhat to doWith Event Gateway
TimeoutsReturn a 200 OK as soon as you accept the event; process in a background jobAccepts the delivery at once, then queues it for your service
DuplicatesCheck a transaction reference or resource ID before giving valueDrops repeats before they reach your handler
RetriesWatch for Failed events; resend them from the Dashboard or the APIAccepts deliveries while your service is down and replays them
Choosing eventsHandle the events you need and acknowledge the restFilters and routes events by type
TestingForward test mode events to localhostForwards to localhost and replays past events
Other limitsConfirm transactions before giving value; protect your secret keyLogs 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:

  1. Verify the signature and return 200 straight away.
  2. Push the event onto a queue (SQS, RabbitMQ or Redis) and process it in a worker. See why to process webhooks asynchronously.
  3. 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:

  1. Build an idempotency key from event and the most specific ID the event has. Charges and transfers have data.reference, refunds data.transaction_reference, disputes data.id, invoices data.invoice_code and subscriptions data.subscription_code. The event part matters for refunds, whose transaction reference stays the same as the status changes.
  2. Use a database table with a unique constraint on the key, and record it in the same transaction as the side effect.
  3. Treat subscription.expiring_cards differently: its data is an array, so there's no single ID to use.
  4. 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:

  1. 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.
  2. To list failures with the API, use GET /integration/webhooks/events?status=Failed, and to find one by reference, use GET /integration/webhooks/events/lookup. Paystack's samples show a status of Failed with a status_detail of retrying or failed, so check status_detail to see whether Paystack is still trying.
  3. 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, use POST /integration/webhooks/events/resend-matching, which is rate limited.
  4. 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:

  1. Dispatch on the event field in the body, because there's no event header to read.
  2. Use the webhook endpoints API to send chosen events to a named endpoint: POST /integration/webhooks/endpoints takes a name, a URL and a list of events, and GET /integration/webhooks/events-catalog lists the names. These return a 403 for integrations without endpoint management.
  3. For a payment flow, start with charge.success. A subscription flow also needs subscription.create, invoice.update and invoice.payment_failed, and a payout flow needs transfer.success, transfer.failed and transfer.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:

  1. Run a tunnel such as the Hookdeck CLI and set its URL as your test webhook URL: hookdeck listen 3000 paystack --path /webhooks/paystack.
  2. Or use Paystack's CLI. webhook listen tunnels test events through ngrok and overwrites the Test Webhook URL on your Dashboard, so set it back afterwards. webhook ping --domain live sends a sample charge.success to your configured URL.
  3. If you use the webhook endpoints API, POST /integration/webhooks/endpoints/{code}/ping checks that an endpoint responds.
  4. 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.

Not affiliated with Paystack. Facts are compiled from public sources and linked inline.