Webhook Events
A collection of endpoints for inspecting, looking up, and resending the webhook events sent to your integration
Copy link List Events
Fetch a paginated list of webhook events for your integration. Filter by category, event type, status, resource id, or date.
Query Parameters
Filter by category, for example transactions
Filter by event name, for example charge.success
Filter by delivery status
EnumDeliveredPendingFailed
Filter by the id of the underlying resource, for example a transaction id
Timestamp to start listing from, for example 2016-09-24T00:00:05.000Z or 2016-09-21
Timestamp to stop listing at, for example 2016-09-24T00:00:05.000Z or 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
Response
200List Events response
3 object properties
GET
/integration/webhooks/eventscurl "https://api.paystack.co/integration/webhooks/events?status=Failed&limit=50" \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.webhookEvents.list({ status: "Failed", limit: 50 });
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.webhook_events.list({ status: "Failed", limit: 50 })
puts response.dataResponse
{
"status": true,
"message": "Webhooks listed",
"data": [
{
"_id": "665f1c2a9d1e4b0012a3c4d5",
"domain": "live",
"category": "transactions",
"event_name": "charge.success",
"webhook_url_code": "WHK_1a2b3c4d",
"category_row_id": 4045667488,
"status": "Failed",
"status_detail": "retrying",
"response_code": 500,
"trial_count": 3,
"createdAt": "2026-07-09T15:17:00.000Z",
"updatedAt": "2026-07-09T15:42:00.000Z"
}
],
"meta": {
"next": "cursor_next",
"previous": null,
"perPage": 50
}
}{
"status": false,
"message": "Invalid query: must be one of next or previous"
}Copy link Look Up an Event
Find a webhook event by its transaction id (not the transaction reference) or event id.
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
Response
200Look Up an Event response
14 object properties
GET
/integration/webhooks/events/lookupcurl "https://api.paystack.co/integration/webhooks/events/lookup?reference=4045667488" \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.webhookEvents.lookup({ reference: "4045667488" });
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.webhook_events.lookup({ reference: "4045667488" })
puts response.dataResponse
{
"status": true,
"message": "Webhook Retrieved",
"data": {
"_id": "6a759cc2289980000e46a716",
"domain": "test",
"category": "cardVerification",
"category_row_id": 5900551050,
"event_name": "zero_charge_authorization.failed",
"status": "Failed",
"status_detail": "failed",
"response_code": 404,
"trial_count": 10,
"createdAt": "2026-08-07T08:52:18.000Z",
"updatedAt": "2026-08-07T13:04:29.000Z",
"webhook_url": "https://example-merchant.com/hooks/paystack",
"webhook_url_code": null,
"event_payload": {
"event": "zero_charge_authorization.failed",
"data": {
"id": 5900551050,
"domain": "test",
"status": "failed",
"reference": "trx_rd227iwg",
"amount": 0,
"currency": "NGN",
"gateway_response": "No gateway was able to process the request"
}
},
"merchant_response_body": {
"success": false,
"error": {
"message": "Not found",
"id": ""
}
}
}
}{
"status": false,
"message": "reference is required"
}{
"status": false,
"message": "Webhook event not found"
}Copy link Fetch Event
Get the full detail of a single webhook event, including the payload sent and the response your endpoint returned.
Path Parameters
The event's _id, from a list item
Response
200Fetch Event response
14 object properties
GET
/integration/webhooks/events/{id}curl "https://api.paystack.co/integration/webhooks/events/665f1c2a9d1e4b0012a3c4d5" \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.webhookEvents.fetch("665f1c2a9d1e4b0012a3c4d5");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.webhook_events.fetch("665f1c2a9d1e4b0012a3c4d5")
puts response.dataResponse
{
"status": true,
"message": "Webhook Retrieved",
"data": {
"_id": "665f1c2a9d1e4b0012a3c4d5",
"domain": "live",
"category": "transactions",
"event_name": "charge.success",
"category_row_id": 4045667488,
"status": "Failed",
"status_detail": "retrying",
"response_code": 500,
"trial_count": 3,
"webhook_url": "https://example-merchant.com/hooks/paystack",
"webhook_url_code": null,
"event_payload": {
"event": "charge.success",
"data": {
"id": 4045667488,
"amount": 15300
}
},
"merchant_response_body": "{\"error\":\"internal server error\"}",
"createdAt": "2026-07-09T15:17:00.000Z",
"updatedAt": "2026-07-09T15:42:00.000Z"
}
}{
"status": false,
"message": "Webhook event not found"
}Copy link 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.
Request Body
Non-empty array of event _ids to resend. Maximum of 100 per request
Response
202Resend Events response
3 object properties
POST
/integration/webhooks/events/resendcurl https://api.paystack.co/integration/webhooks/events/resend \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"ids":["665f1c2a9d1e4b0012a3c4d5","665a0b119d1e4b0012a3bd90"]}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.webhookEvents.resend({ ids: ["665f1c2a9d1e4b0012a3c4d5", "665a0b119d1e4b0012a3bd90"] });
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.webhook_events.resend({ ids: ["665f1c2a9d1e4b0012a3c4d5", "665a0b119d1e4b0012a3bd90"] })
puts response.dataResponse
{
"status": true,
"message": "Resend accepted",
"data": {
"count": 2,
"failed": 0,
"failed_ids": []
}
}{
"status": false,
"message": "ids must be a non-empty array"
}Copy link 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.
Query Parameters
Set to true to return the matching count without resending anything
Request Body
The same filters accepted by List Events (category, event_type, status, category_row_id, from, to). All optional
Response
200Resend Matching Events preview response (preview=true)
1 object property
POST
/integration/webhooks/events/resend-matchingcurl https://api.paystack.co/integration/webhooks/events/resend-matching \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"status":"Failed","category":"transactions","event_type":"charge.success","from":"2026-07-01","to":"2026-07-09"}}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.webhookEvents.resendMatching({
filters: { status: "Failed", category: "transactions", event_type: "charge.success", from: "2026-07-01", to: "2026-07-09" },
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.webhook_events.resend_matching({
filters: { status: "Failed", category: "transactions", event_type: "charge.success", from: "2026-07-01", to: "2026-07-09" },
})
puts response.dataResponse
{
"status": true,
"message": "Preview",
"data": {
"count": 128
}
}{
"status": true,
"message": "Resend accepted",
"data": {
"count": 128,
"skipped": 0,
"batch_id": "rbatch_77cd41"
}
}{
"status": false,
"message": "Resend rate limit exceeded, please try again later"
}