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.

35 events covered

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

Signature header
x-paystack-signature

Format: <128 lowercase hex characters>

Scheme
HMAC-SHA512
Signed material
{raw body}

The request body exactly as sent, with no timestamp. Re-serialised JSON can fail.

How events are identified
event field in the body
Body format
JSON

Content type: application/json.

Envelope
event, data
Agent skill
npx skills add hookdeck/webhook-skills --skill paystack-webhooks

Verify Paystack webhooks →

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: 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

  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 →
  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 →
  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 →
  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 →

Paystack webhook best practices

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

charge.dispute.create · .dispute.remind · .dispute.resolve · .failed +1

5 4
preauthorization

preauthorization.capture.failed · .capture.success · .release.failed · .release.success +1

5 5
refund

refund.failed · .needs-attention · .pending · .processed +1

5 5
subscription

subscription.create · .disable · .expiring_cards · .not_renew

4 4
invoice

invoice.create · .payment_failed · .update

3 3
transfer

transfer.failed · .reversed · .success

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.

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