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

categorystring
Filter by category, for example transactions
event_typestring
Filter by event name, for example charge.success
statusstring
Filter by delivery status
EnumDeliveredPendingFailed
category_row_idstring
Filter by the id of the underlying resource, for example a transaction id
fromstring
Timestamp to start listing from, for example 2016-09-24T00:00:05.000Z or 2016-09-21
tostring
Timestamp to stop listing at, for example 2016-09-24T00:00:05.000Z or 2016-09-21
limitinteger
Number of events to return per page. Defaults to 20
nextstring
Cursor from a previous response's meta.next, for the next page. Don't send this alongside previous
previousstring
Cursor from a previous response's meta.previous, for the previous page. Don't send this alongside next

Response

200List Events response
statusrequiredboolean
messagerequiredstring
datarequiredarray[object]
metarequiredobject
3 object properties
nextstring
previousstring
perPagerequiredinteger
GET/integration/webhooks/events
curl "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.data
Response
{
  "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

referencerequiredstring
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
statusrequiredboolean
messagerequiredstring
datarequiredobject
14 object properties
_idrequiredstring
domainrequiredstring
categoryrequiredstring
category_row_idrequiredinteger
event_namerequiredstring
statusrequiredstring
status_detailrequiredstring
response_coderequiredinteger
trial_countrequiredinteger
webhook_urlrequiredstring
event_payloadrequiredobject
merchant_response_bodyrequiredobject
createdAtrequiredstring
updatedAtrequiredstring
GET/integration/webhooks/events/lookup
curl "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.data
Response
{
  "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

idrequiredstring
The event's _id, from a list item

Response

200Fetch Event response
statusrequiredboolean
messagerequiredstring
datarequiredobject
14 object properties
_idrequiredstring
domainrequiredstring
categoryrequiredstring
event_namerequiredstring
category_row_idrequiredinteger
statusrequiredstring
status_detailrequiredstring
response_coderequiredinteger
trial_countrequiredinteger
webhook_urlrequiredstring
event_payloadrequiredobject
merchant_response_bodyrequiredstring
createdAtrequiredstring
updatedAtrequiredstring
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.data
Response
{
  "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

idsrequiredarray[string]
Non-empty array of event _ids to resend. Maximum of 100 per request

Response

202Resend Events response
statusrequiredboolean
messagerequiredstring
datarequiredobject
3 object properties
countrequiredinteger
failedrequiredinteger
failed_idsrequiredarray[string]
POST/integration/webhooks/events/resend
curl https://api.paystack.co/integration/webhooks/events/resend \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":["665f1c2a9d1e4b0012a3c4d5","665a0b119d1e4b0012a3bd90"]}' \
  -X POST
import { 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.data
Response
{
  "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

previewboolean
Set to true to return the matching count without resending anything

Request Body

filtersobject
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)
statusrequiredboolean
messagerequiredstring
datarequiredobject
1 object property
countrequiredinteger
POST/integration/webhooks/events/resend-matching
curl 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 POST
import { 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.data
Response
{
  "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"
}