Webhook Endpoints

The Webhook Endpoints API lets you send webhook events to multiple URLs, and choose the events each URL receives. Learn how to use it in the webhooks guide.

Webhook endpoints are in pilot. To request access, email [email protected]. Integrations outside the pilot get a 403.

Restricted keys need the webhooks:read scope for GET requests, and webhooks:write for all other requests.

List Available Events

List the events you can subscribe a webhook endpoint to, grouped by category and sorted by name. An event's description is null if it doesn't have one.

Headers

Set value to Bearer SECRET_KEY

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

1{
2  "status": true,
3  "message": "Webhook events catalog retrieved",
4  "data": {
5    "refunds": [
6      {
7        "event_name": "refund.processed",
8        "description": "A processed refund"
9      }
10    ],
11    "transactions": [
12      {
13        "event_name": "charge.failed",
14        "description": "A failed charge"
15      },
16      {
17        "event_name": "charge.success",
18        "description": "A successful charge"
19      }
20    ]
21  }
22}

List Webhook Endpoints

List the webhook endpoints on your integration. Each item includes the number of events but not the events themselves. A null cursor in meta means there are no more pages in that direction.

Headers

Set value to Bearer SECRET_KEY

Query Parameters

Number of endpoints to return per page, from 1 to 50. Defaults to 50, and any value outside that range is treated as 50

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/endpoints?limit=20"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X GET

1{
2  "status": true,
3  "message": "Webhook endpoints retrieved",
4  "data": [
5    {
6      "webhook_url_code": "WHK_1a2b3c4d",
7      "name": "Order fulfillment",
8      "webhook_url": "https://example.com/webhooks/paystack",
9      "enabled": true,
10      "event_count": 2
11    }
12  ],
13  "meta": {
14    "next": "V0hLXzk5",
15    "previous": null,
16    "perPage": 20
17  }
18}

Fetch Webhook Endpoint

Get a webhook endpoint and its events, grouped by category.

Headers

Set value to Bearer SECRET_KEY

Path Parameters

The endpoint's webhook_url_code, for example WHK_1a2b3c4d

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

1{
2  "status": true,
3  "message": "Webhook endpoint retrieved",
4  "data": {
5    "webhook_url_code": "WHK_1a2b3c4d",
6    "name": "Order fulfillment",
7    "webhook_url": "https://example.com/webhooks/paystack",
8    "enabled": true,
9    "events": {
10      "transactions": [
11        "charge.failed",
12        "charge.success"
13      ]
14    },
15    "event_count": 2
16  }
17}

Create Webhook Endpoint

Create a webhook endpoint subscribed to a list of events. Each endpoint's URL must be unique within the environment, ignoring the case of the scheme and host. When events is ["*"], Paystack subscribes the endpoint to every event available at the time of the request, and the response lists them.

Headers

Set value to Bearer SECRET_KEY

Set value to application/json

Body Parameters

A label for the endpoint, up to 120 characters. Leading and trailing spaces are removed

The https URL to send events to, up to 2,048 characters. It must be publicly reachable and must not include a username or password

Names of the events to send to this endpoint, from List Available Events. Must contain at least one event, with no duplicates. Send ["*"] to subscribe to every event currently in the catalog. You can't combine "*" with named events

1#!/bin/sh
2url="https://api.paystack.co/integration/webhooks/endpoints"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{
6  "name": "Order fulfillment",
7  "url": "https://example.com/webhooks/paystack",
8  "events": [
9    "charge.success",
10    "charge.failed"
11  ]
12}'
13
14curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST

1{
2  "status": true,
3  "message": "Webhook endpoint created",
4  "data": {
5    "webhook_url_code": "WHK_1a2b3c4d",
6    "name": "Order fulfillment",
7    "webhook_url": "https://example.com/webhooks/paystack",
8    "enabled": true,
9    "events": [
10      "charge.success",
11      "charge.failed"
12    ],
13    "event_count": 2
14  }
15}

Update Webhook Endpoint

Update a webhook endpoint's name, URL, events, or status. Send at least one field. events replaces the endpoint's current events.

Headers

Set value to Bearer SECRET_KEY

Set value to application/json

Path Parameters

The endpoint's webhook_url_code, for example WHK_1a2b3c4d

Body Parameters

A label for the endpoint, up to 120 characters

The https URL to send events to, up to 2,048 characters

Replaces the endpoint's full list of events. Names of the events to send to this endpoint, from List Available Events. Must contain at least one event, with no duplicates. Send ["*"] to subscribe to every event currently in the catalog. You can't combine "*" with named events

Set to false to stop sending events to this endpoint, or true to resume. Setting it to false keeps the endpoint's URL and events

1#!/bin/sh
2url="https://api.paystack.co/integration/webhooks/endpoints/WHK_1a2b3c4d"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{
6  "enabled": false
7}'
8
9curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X PATCH

1{
2  "status": true,
3  "message": "Webhook endpoint updated",
4  "data": {
5    "webhook_url_code": "WHK_1a2b3c4d",
6    "name": "Order fulfillment",
7    "webhook_url": "https://example.com/webhooks/paystack",
8    "enabled": false,
9    "events": [
10      "charge.success",
11      "charge.failed"
12    ],
13    "event_count": 2
14  }
15}

Delete Webhook Endpoint

Delete a webhook endpoint.

Headers

Set value to Bearer SECRET_KEY

Path Parameters

The endpoint's webhook_url_code, for example WHK_1a2b3c4d

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

1{
2  "status": true,
3  "message": "Webhook endpoint deleted",
4  "data": {
5    "webhook_url_code": "WHK_1a2b3c4d"
6  }
7}

Ping Webhook Endpoint

Send a signed test event, with event set to ping, to a webhook endpoint and return the result. data.ok is true only for a 2xx status from the URL, and data.http_status is null if Paystack couldn't reach it. You can ping up to 10 times every 60 seconds in each environment.

Headers

Set value to Bearer SECRET_KEY

Path Parameters

The endpoint's webhook_url_code, for example WHK_1a2b3c4d

1#!/bin/sh
2url="https://api.paystack.co/integration/webhooks/endpoints/WHK_1a2b3c4d/ping"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X POST

1{
2  "status": true,
3  "message": "Ping sent",
4  "data": {
5    "ok": true,
6    "http_status": 200,
7    "latency_ms": 143
8  }
9}