Skip to content
HookDeploy

Paystack webhooks

Last verified against Paystack's documentation on September 27, 2026.

On this page ↓

Paystack sends webhooks when something happens to a charge, a transfer, a refund, a subscription, or an invoice. It signs each request with an HMAC-SHA512 of the body, keyed with your secret key, the same key you use for API calls. Paystack’s own example verifies a re-serialized body, which is the most common source of signature failures. This page covers what Paystack sends, how it delivers, how to fix the common errors, and where HookDeploy fits.

What Paystack sends webhooks for

AreaExample eventsTypical use
Chargescharge.success, charge.dispute.createGive value after a successful payment
Transferstransfer.success, transfer.failed, transfer.reversedTrack payouts
Refundsrefund.processed, refund.failedRecord refunds
Subscriptionssubscription.create, subscription.disable, invoice.payment_failedKeep recurring billing in sync

Each webhook is a JSON POST with an event name and the object under data, including its reference.

How Paystack delivers webhooks

BehaviorDetail
Method and formatPOST with a JSON body
Signature headerx-paystack-signature: hex HMAC-SHA512 of the body, keyed with your secret key
Success200
Retries (live)Every 3 minutes for the first 4 tries, then hourly for the next 72 hours
Retries (test)Hourly for 10 hours, with a 30-second request timeout
Source IPsPublished, so you can allowlist them
VerificationCall the verify transaction endpoint before giving value

Common Paystack webhook errors and how to fix them

Signature doesn’t match

  • Re-serialized body. Paystack’s own example hashes JSON.stringify(req.body), which only works when re-serializing reproduces Paystack’s exact bytes. Hash the raw body.
  • Wrong algorithm. It’s SHA-512, not SHA-256.
  • Wrong key. Use the secret key for the same mode, test or live.

Value given for the wrong amount

A valid signature proves Paystack sent the event, not that the amount matches your order. Call Paystack’s verify transaction endpoint and check the amount and currency before giving value.

Duplicate events

Paystack retries for up to 72 hours. Deduplicate on the event name together with the transaction reference.

URL not reachable

Paystack needs a public URL. If you use .htaccess rewrites, include the trailing slash that your server expects.

Why use HookDeploy with Paystack

Capture every event

HookDeploy captures every Paystack webhook at Cloudflare’s edge and responds right away, before forwarding it to your server. If your server is down, events wait in HookDeploy instead of piling up in Paystack’s 72-hour retry schedule.

  • Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
  • Incidents. Forward failures are grouped into incidents, and you can bulk-replay them once your server recovers.
  • History. HookDeploy keeps captured webhooks for your plan’s retention period, from 7 days on Free to 365 days on Enterprise.

Allowlist Paystack’s IPs

Paystack publishes the IP addresses it sends webhooks from. Add them to the endpoint’s IP allowlist on the Security tab, under Network, and anything else is rejected before it’s captured. IP allowlists are available on Starter and above.

One webhook, many systems

Send each Paystack event to your app, your accounting or ERP system, and an alert channel in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.

Deliver to systems Paystack can’t reach

The HookDeploy Agent connects outward from your network over mTLS and delivers events to a local port, so a billing or fulfillment service in a private network can receive Paystack events with no public endpoint.

Develop against real events

A tap sends a temporary copy of live Paystack events to 127.0.0.1 on your machine while production keeps receiving them.

Know the limits

  • Transformations. A transformation changes the body, and then the signature won’t verify at that destination.
  • Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a 429, which Paystack treats as a failed delivery. Paid plans keep accepting traffic past the included volume.

Retries, replays, and duplicates

Paystack’s signature covers only the body, with no timestamp, and HookDeploy forwards the body and x-paystack-signature header unchanged, so retries and replays verify like the original delivery. A privacy filter that changes the stored copy used for retries and replays breaks the signature.

Paystack’s retries, HookDeploy’s retries, and replays can all deliver the same event. Deduplicate on the event name and reference.

Set up Paystack with HookDeploy

  1. In HookDeploy, create an endpoint (for example, Paystack live) and copy its URL.
  2. On the endpoint’s Security tab, under Network, add Paystack’s published webhook IP addresses (Starter and above).
  3. On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery, and set its retries.
  4. In the Paystack Dashboard, go to Settings, then API Keys & Webhooks, and set your HookDeploy URL as the webhook URL for the mode you’re configuring.
  5. Make a test payment, and confirm the event appears in HookDeploy and reaches your handler.

Example handler (Node.js and Express)

import crypto from 'node:crypto';
import express from 'express';

const app = express();

// Raw body parser on this route, registered before any global JSON middleware.
app.post('/webhooks/paystack', express.raw({ type: 'application/json' }), async (req, res) => {
  const expected = crypto
    .createHmac('sha512', process.env.PAYSTACK_SECRET_KEY)   // SHA-512, your secret key
    .update(req.body)                          // raw bytes, not JSON.stringify(req.body)
    .digest('hex');
  const received = req.get('x-paystack-signature') ?? '';
  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.status(401).send('Invalid signature');

  res.sendStatus(200);
  const event = JSON.parse(req.body.toString('utf8'));
  await enqueue({ name: event.event, reference: event.data?.reference, data: event.data });
  // Deduplicate on name plus reference, and verify the transaction via the API before giving value.
});

FAQ

How do I verify a Paystack webhook?

Compute a hex HMAC-SHA512 of the raw request body using your Paystack secret key, and compare it to the x-paystack-signature header with a constant-time comparison.

Why does my Paystack signature check fail?

Usually because the body was parsed and re-serialized before hashing, which Paystack's own example does. Hash the raw body. Also check that you're using SHA-512 and the secret key for the right mode.

How does Paystack retry webhooks?

In live mode, every 3 minutes for the first 4 tries, then hourly for the next 72 hours. In test mode, hourly for 10 hours.

Should I trust the amount in a Paystack webhook?

Verify it. Call Paystack's verify transaction endpoint and check the amount and currency before giving value.

Can I allowlist Paystack's IP addresses?

Yes. Paystack publishes the IP addresses its webhooks come from, and you can add them to HookDeploy's endpoint IP allowlist.

Does HookDeploy break Paystack signature verification?

No. The signature covers only the body, and HookDeploy forwards the body and x-paystack-signature header unchanged, so first deliveries, retries, and replays all verify.

Capture Paystack webhooks free

Start free