Paystack webhooks
Paystack webhooks are HTTP POST requests that Paystack sends to your webhook URL when something happens on your account, such as a charge succeeding, a transfer failing or a subscription being created.
How Paystack webhooks work
Webhooks push events to your server as they happen, so you don't have to poll the API to learn that a payment went through. They also cover the case where a customer pays but never returns to your callback URL. Paystack sends a POST with a JSON body to your webhook URL, and counts any 2xx response as delivered. Test and live modes have separate webhook URLs.
Every body has the same top level: event says what happened, such as charge.success, and data holds the object it happened to. Paystack's documented examples carry no event ID or version field, so what you deduplicate on depends on the event.
Key facts
{raw body} The request body exactly as sent, with no timestamp. Re-serialised JSON can fail.
Setting up Paystack webhooks
- Set your webhook URL in the Paystack Dashboard under Settings > API Keys & Webhooks, once for test mode and once for live.
- To route chosen events to a named endpoint, use
POST /integration/webhooks/endpoints, and list the event names withGET /integration/webhooks/events-catalog. Both return a403for integrations without endpoint management. - To test locally, run the Hookdeck CLI:
hookdeck listen 3000 paystack --path /webhooks/paystack. Paystack's own CLI haswebhook listen, which works in test mode only and overwrites your Test Webhook URL. - Resend events from Developers > Webhooks on the new Paystack Dashboard, or with
POST /integration/webhooks/events/resend.
Delivery behaviour
respond at once return 200 OK as soon as you accept the event; a slow response can leave a delivery pending or failed Retries about 72 hours automatic; that figure comes from Paystack's Magento plugin, and the schedule is in Paystack's webhooks guide After retries marked Failed resend it from the Dashboard or with the API once you've fixed the cause Duplicates can happen check a transaction reference or resource ID before giving value Known failure modes
From Hookdeck's Paystack guide →-
Duplicate deliveries
Paystack can deliver an event more than once, particularly when retries occur. Check a transaction reference or resource ID before giving value, so a customer isn't credited twice.
Handle duplicates → -
Slow handlers
A delivery can stay pending or fail if your server takes too long to respond. Return
Handle timeouts →200 OKas soon as you accept the event, then do the work in the background. -
Events that end up Failed
When Paystack can't deliver an event it marks it Failed. Fix the cause, then resend it from Developers > Webhooks or with the API. A resend goes to the URL configured now, which may not be the original.
Retries and resends → -
Replayed requests
Handle duplicates →x-paystack-signaturecovers only the body, so a captured request still verifies later. Record each event you process, so a replayed one has no effect.
Paystack webhook best practices
- Verify every signature.
Use SHA-512 over the raw body. Without this check, anyone who finds your URL can send a fake
charge.success. - Return a 200 before doing any work.
Paystack's advice is to return
200 OKas soon as you accept the event, because a slow response can leave a delivery pending or failed. - Process events in the background. A queue keeps the request path short, and a spike in events doesn't slow your responses.
- Deduplicate on a reference or resource ID. Retries can deliver an event again. Check whether you've already processed it before you give value.
- Confirm the transaction before giving value.
Call
GET /transaction/verify/{reference}and compare the amount and status with what you expected. - Handle only the events you need.
A single webhook URL can receive events for every Paystack product you use, so return a
200for the ones you ignore.
Common Paystack webhook events
Payments
charge.success | Charge completes successfully |
charge.failed | Charge attempt fails |
refund.processed | Processor completes a refund |
Transfers
transfer.success | Outgoing transfer completes |
transfer.failed | Outgoing transfer fails |
transfer.reversed | Outgoing transfer is reversed |
Subscriptions
subscription.create | New subscription is created |
subscription.disable | Subscription is disabled |
invoice.update | Invoice changes, usually after a successful charge |
invoice.payment_failed | Payment attempt on an invoice fails |
Events by resource
| Resource | Events | Payloads |
|---|---|---|
charge | 5 | 4 |
preauthorization | 5 | 5 |
refund | 5 | 5 |
subscription | 4 | 4 |
invoice | 3 | 3 |
transfer | 3 | 3 |
1 more resource, including Other Paystack events. All 35 events →
In this hub
| Webhook events → | Every covered Paystack event, with payloads where the registry has them. |
| MCP events → | How an agent subscribes to Paystack events as MCP events. |
| Verify signatures → | Signature facts, verification code and common failures. |
| Production guide → | Production problems: timeouts, duplicates, ordering and retries, and how to handle them. |
| Agent skill → | Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill paystack-webhooks |
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.