Webhook Events

The Webhook Events API lets you inspect events, server responses, and resend the webhook events sent to your integration in each environment.

List Events

Fetch a paginated list of webhook events for your integration. Filter by category, event type, status, resource id, or date.

Headers

Set value to Bearer SECRET_KEY

Query Parameters

Filter by category, e.g. transactions

Filter by event name, e.g. charge.success

Filter by delivery status. One of Delivered, Pending, Failed

Filter by the id of the underlying resource, e.g. a transaction id

A timestamp from which to start listing webhook events e.g. 2016-09-24T00:00:05.000Z, 2016-09-21

A timestamp at which to stop listing webhook events e.g. 2016-09-24T00:00:05.000Z, 2016-09-21

Number of events to return per page. Defaults to 20

Cursor from a previous response's meta.next, for the next page. Don't send this alongside previous

Cursor from a previous response's meta.previous, for the previous page. Don't send this alongside next

1#!/bin/sh
2url="https://api.paystack.co/integration/webhooks/events?status=Failed&limit=50"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X GET

1{
2  "status": true,
3  "message": "Webhooks listed",
4  "data": [
5    {
6      "_id": "665f1c2a9d1e4b0012a3c4d5",
7      "domain": "live",
8      "category": "transactions",
9      "event_name": "charge.success",
10      "category_row_id": 4045667488,
11      "status": "Failed",
12      "status_detail": "retrying",
13      "response_code": 500,
14      "trial_count": 3,
15      "createdAt": "2026-07-09T15:17:00.000Z",
16      "updatedAt": "2026-07-09T15:42:00.000Z"
17    }
18  ],
19  "meta": {
20    "next": "cursor_next",
21    "previous": null,
22    "perPage": 50
23  }
24}

Look Up an Event

Find a webhook event by its transaction id (not the transaction reference) or event id.

Headers

Set value to Bearer SECRET_KEY

Query Parameters

The transaction id or event id to look up, not the transaction reference. An event id matches directly; anything else is matched against the underlying transaction id

1#!/bin/sh
2url="https://api.paystack.co/integration/webhooks/events/lookup?reference=4045667488"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X GET

1{
2  "status": true,
3  "message": "Webhook Retrieved",
4  "data": {
5    "_id": "6a759cc2289980000e46a716",
6    "domain": "test",
7    "category": "cardVerification",
8    "category_row_id": 5900551050,
9    "event_name": "zero_charge_authorization.failed",
10    "status": "Failed",
11    "status_detail": "failed",
12    "response_code": 404,
13    "trial_count": 10,
14    "createdAt": "2026-08-07T08:52:18.000Z",
15    "updatedAt": "2026-08-07T13:04:29.000Z",
16    "webhook_url": "https://example-merchant.com/hooks/paystack",
17    "webhook_url_code": null,
18    "event_payload": {
19      "event": "zero_charge_authorization.failed",
20      "data": {
21        "id": 5900551050,
22        "domain": "test",
23        "status": "failed",
24        "reference": "trx_rd227iwg",
25        "amount": 0,
26        "currency": "NGN",
27        "gateway_response": "No gateway was able to process the request"
28      }
29    },
30    "merchant_response_body": {
31      "success": false,
32      "error": {
33        "message": "Not found",
34        "id": ""
35      }
36    }
37  }
38}

Fetch Event

Get the full detail of a single webhook event, including the payload sent and the response your endpoint returned.

Headers

Set value to Bearer SECRET_KEY

Path Parameters

The event's _id, from a list item

1#!/bin/sh
2url="https://api.paystack.co/integration/webhooks/events/665f1c2a9d1e4b0012a3c4d5"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X GET

1{
2  "status": true,
3  "message": "Webhook Retrieved",
4  "data": {
5    "_id": "665f1c2a9d1e4b0012a3c4d5",
6    "domain": "live",
7    "category": "transactions",
8    "event_name": "charge.success",
9    "category_row_id": 4045667488,
10    "status": "Failed",
11    "status_detail": "retrying",
12    "response_code": 500,
13    "trial_count": 3,
14    "webhook_url": "https://example-merchant.com/hooks/paystack",
15    "webhook_url_code": null,
16    "event_payload": {
17      "event": "charge.success",
18      "data": {
19        "id": 4045667488,
20        "amount": 15300
21      }
22    },
23    "merchant_response_body": "{\"error\":\"internal server error\"}",
24    "createdAt": "2026-07-09T15:17:00.000Z",
25    "updatedAt": "2026-07-09T15:42:00.000Z"
26  }
27}

Resend Events

Resend a specific set of webhook events to your current webhook URL. Resending isn't idempotent—submitting the same event id twice delivers it twice.

Headers

Set value to Bearer SECRET_KEY

Set value to application/json

Body Parameters

Non-empty array of event _ids to resend. Maximum of 100 per request

1#!/bin/sh
2url="https://api.paystack.co/integration/webhooks/events/resend"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{
6  "ids": ["665f1c2a9d1e4b0012a3c4d5", "665a0b119d1e4b0012a3bd90"]
7}'
8
9curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST

1{
2  "status": true,
3  "message": "Resend accepted",
4  "data": {
5    "count": 2,
6    "failed": 0,
7    "failed_ids": []
8  }
9}

Resend Matching Events

Resend every webhook event matching a filter. Pass preview=true first to confirm how many events match before you commit to the resend.

Headers

Set value to Bearer SECRET_KEY

Set value to application/json

Query Parameters

Set to true to return the matching count without resending anything

Body Parameters

The same filters accepted by List Webhook Events: category, event_type, status, category_row_id, from, to. All optional

1#!/bin/sh
2url="https://api.paystack.co/integration/webhooks/events/resend-matching"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{
6  "filters": {
7    "status": "Failed",
8    "category": "transactions",
9    "event_type": "charge.success",
10    "from": "2026-07-01",
11    "to": "2026-07-09"
12  }
13}'
14
15curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST

1{
2  "status": true,
3  "message": "Preview",
4  "data": {
5    "count": 128
6  }
7}