# 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.

Agent skill: `npx skills add hookdeck/webhook-skills --skill paystack-webhooks` ([details](https://hookdeck.com/webhooks/paystack/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [Paystack's official docs](https://paystack.com/docs/payments/webhooks/).

[Overview](https://hookdeck.com/webhooks/paystack) · [Webhook events (35)](https://hookdeck.com/webhooks/paystack/events) · [MCP events](https://hookdeck.com/webhooks/paystack/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/paystack/verify) · [Production guide](https://hookdeck.com/webhooks/paystack/guide-duplicates-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/paystack/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `x-paystack-signature` Format: <128 lowercase hex characters> | [Paystack docs](https://raw.githubusercontent.com/PaystackHQ/plugin-magento-2/master/marketplace/src/reference-manual.md) |
| Scheme | `HMAC-SHA512` | [Paystack docs](https://raw.githubusercontent.com/PaystackHQ/plugin-magento-2/master/marketplace/src/reference-manual.md) |
| Signed material | `{raw body}` The request body exactly as sent, with no timestamp. Re-serialised JSON can fail. | [Paystack docs](https://raw.githubusercontent.com/PaystackHQ/plugin-magento-2/master/marketplace/src/reference-manual.md) |
| How events are identified | `event field in the body` | [Paystack docs](https://raw.githubusercontent.com/PaystackOSS/doc-code-snippets/main/src/doc/payments/webhooks/events/customer-id-failed.json) |
| Body format | `JSON` Content type: application/json. | [Paystack docs](https://raw.githubusercontent.com/PaystackOSS/doc-code-snippets/main/src/doc/payments/webhooks/verifying-signature/index.js) |
| Envelope | `event, data` | [Paystack docs](https://paystack.com/docs/payments/webhooks/) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill paystack-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/paystack/skill) |

[Verify Paystack webhooks](https://hookdeck.com/webhooks/paystack/verify)

## 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.

## 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 with `GET /integration/webhooks/events-catalog`. Both return a `403` for integrations without endpoint management.
- To test locally, run the [Hookdeck CLI](/docs/cli): `hookdeck listen 3000 paystack --path /webhooks/paystack`. Paystack's own CLI has `webhook 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

- **Timeout:** respond at once. return `200 OK` as soon as you accept the event; a slow response can leave a delivery pending or failed. [Guide](https://hookdeck.com/webhooks/paystack/guide-duplicates-retries-timeouts#timeouts)
- **Retries:** about 72 hours. automatic; that figure comes from Paystack's Magento plugin, and the schedule is in [Paystack's webhooks guide](https://paystack.com/docs/payments/webhooks/). [Guide](https://hookdeck.com/webhooks/paystack/guide-duplicates-retries-timeouts#retries)
- **After retries:** marked Failed. resend it from the Dashboard or with the API once you've fixed the cause. [Guide](https://hookdeck.com/webhooks/paystack/guide-duplicates-retries-timeouts#retries)
- **Duplicates:** can happen. check a transaction reference or resource ID before giving value. [Guide](https://hookdeck.com/webhooks/paystack/guide-duplicates-retries-timeouts#duplicates)

## Known failure modes

1. **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](https://hookdeck.com/webhooks/paystack/guide-duplicates-retries-timeouts#duplicates)
2. **Slow handlers.** A delivery can stay pending or fail if your server takes too long to respond. Return `200 OK` as soon as you accept the event, then do the work in the background. [Handle timeouts](https://hookdeck.com/webhooks/paystack/guide-duplicates-retries-timeouts#timeouts)
3. **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](https://hookdeck.com/webhooks/paystack/guide-duplicates-retries-timeouts#retries)
4. **Replayed requests.** `x-paystack-signature` covers only the body, so a captured request still verifies later. Record each event you process, so a replayed one has no effect. [Handle duplicates](https://hookdeck.com/webhooks/paystack/guide-duplicates-retries-timeouts#duplicates)

From [Hookdeck's Paystack guide](https://hookdeck.com/webhooks/paystack/guide-duplicates-retries-timeouts).

## Paystack webhook best practices

- **[Verify every signature](https://hookdeck.com/webhooks/paystack/verify).** 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](https://hookdeck.com/webhooks/paystack/guide-duplicates-retries-timeouts#timeouts).** Paystack's advice is to return `200 OK` as soon as you accept the event, because a slow response can leave a delivery pending or failed.
- **[Process events in the background](https://hookdeck.com/webhooks/paystack/guide-duplicates-retries-timeouts#timeouts).** A queue keeps the request path short, and a spike in events doesn't slow your responses.
- **[Deduplicate on a reference or resource ID](https://hookdeck.com/webhooks/paystack/guide-duplicates-retries-timeouts#duplicates).** Retries can deliver an event again. Check whether you've already processed it before you give value.
- **[Confirm the transaction before giving value](https://hookdeck.com/webhooks/paystack/guide-duplicates-retries-timeouts#other-limits).** Call `GET /transaction/verify/{reference}` and compare the amount and status with what you expected.
- **[Handle only the events you need](https://hookdeck.com/webhooks/paystack/guide-duplicates-retries-timeouts#choosing-events).** A single webhook URL can receive events for every Paystack product you use, so return a `200` for the ones you ignore.

## Common Paystack webhook events

### Payments

- [charge.success](https://hookdeck.com/webhooks/paystack/events#charge.success): Charge completes successfully
- [charge.failed](https://hookdeck.com/webhooks/paystack/events#charge.failed): Charge attempt fails
- [refund.processed](https://hookdeck.com/webhooks/paystack/events#refund.processed): Processor completes a refund

### Transfers

- [transfer.success](https://hookdeck.com/webhooks/paystack/events#transfer.success): Outgoing transfer completes
- [transfer.failed](https://hookdeck.com/webhooks/paystack/events#transfer.failed): Outgoing transfer fails
- [transfer.reversed](https://hookdeck.com/webhooks/paystack/events#transfer.reversed): Outgoing transfer is reversed

### Subscriptions

- [subscription.create](https://hookdeck.com/webhooks/paystack/events#subscription.create): New subscription is created
- [subscription.disable](https://hookdeck.com/webhooks/paystack/events#subscription.disable): Subscription is disabled
- [invoice.update](https://hookdeck.com/webhooks/paystack/events#invoice.update): Invoice changes, usually after a successful charge
- [invoice.payment_failed](https://hookdeck.com/webhooks/paystack/events#invoice.payment_failed): Payment attempt on an invoice fails

## Events by resource

| Resource | Events | Payloads |
|---|---|---|
| [charge](https://hookdeck.com/webhooks/paystack/events#resource-charge) | 5 | 4 |
| [preauthorization](https://hookdeck.com/webhooks/paystack/events#resource-preauthorization) | 5 | 5 |
| [refund](https://hookdeck.com/webhooks/paystack/events#resource-refund) | 5 | 5 |
| [subscription](https://hookdeck.com/webhooks/paystack/events#resource-subscription) | 4 | 4 |
| [invoice](https://hookdeck.com/webhooks/paystack/events#resource-invoice) | 3 | 3 |
| [transfer](https://hookdeck.com/webhooks/paystack/events#resource-transfer) | 3 | 3 |

1 more resource. [All 35 events](https://hookdeck.com/webhooks/paystack/events)

## In this hub

- [Webhook events](https://hookdeck.com/webhooks/paystack/events): Every covered Paystack event, with payloads where the registry has them.
- [MCP events](https://hookdeck.com/webhooks/paystack/mcp-events): How an agent subscribes to Paystack events as MCP events.
- [Verify signatures](https://hookdeck.com/webhooks/paystack/verify): Signature facts, verification code and common failures.
- [Production guide](https://hookdeck.com/webhooks/paystack/guide-duplicates-retries-timeouts): Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
- [Agent skill](https://hookdeck.com/webhooks/paystack/skill): Install the webhook skill in your coding agent. `npx skills add hookdeck/webhook-skills --skill paystack-webhooks`
---

Not affiliated with Paystack. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/paystack.json) · [Report a correction](https://hookdeck.com/contact)
