Create a webhook endpoint

curl --request POST \
  --url https://api.paystack.com/v1/notifications/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "event_categories": []
}
'

{
  "status": true,
  "message": "Webhook endpoint created",
  "code": "ok",
  "data": {
    "id": "whr_01HXYZABC1234567890ABCDEFG",
    "url": "https://merchant.example.com/webhooks",
    "event_categories": [
      "onramp",
      "conversion"
    ],
    "active": false,
    "created_at": "2026-05-26T12:00:00.000Z",
    "updated_at": "2026-05-26T12:00:00.000Z",
    "signing_secret": "whsec_K5x...base64...=="
  },
  "meta": {
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Notification Webhooks

Create a webhook endpoint

Subscribe to one or more event categories — coarse families of events rather than individual topics. The available categories are: onramp, offramp, conversion, transfer, deposit, kyc.

The response includes a signing_secret (prefixed whsec_) returned in plaintext exactly once — on create and on rotate-secret only. Store it securely; you cannot retrieve it again. Use it to verify the signature on every delivered event.

New endpoints are created inactive (active: false). Activate the endpoint with a PATCH once you have stored the signing secret and are ready to receive deliveries.

Body

url — required. Must be a valid HTTPS URL.
event_categories — required. Non-empty array of event categories (see above). Unknown values are rejected with 400.

Example

POST /v1/notifications/webhooks
{
  "url": "https://merchant.example.com/webhooks",
  "event_categories": ["onramp", "conversion"]
}

POST

notifications

webhooks

Create a webhook endpoint

curl --request POST \
  --url https://api.paystack.com/v1/notifications/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "event_categories": []
}
'

{
  "status": true,
  "message": "Webhook endpoint created",
  "code": "ok",
  "data": {
    "id": "whr_01HXYZABC1234567890ABCDEFG",
    "url": "https://merchant.example.com/webhooks",
    "event_categories": [
      "onramp",
      "conversion"
    ],
    "active": false,
    "created_at": "2026-05-26T12:00:00.000Z",
    "updated_at": "2026-05-26T12:00:00.000Z",
    "signing_secret": "whsec_K5x...base64...=="
  },
  "meta": {
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Authorizations

Authorization

string

header

required

API key issued during merchant onboarding.

Headers

Idempotency-Key

string

Optional client-supplied key. Identical key + identical body within 24h replays the original response. Identical key + different body returns 409 idempotency_conflict. The hash is over raw bytes — clients retrying must send the byte-identical body; a re-serialised JSON payload will produce a different hash and a 409. Strongly recommended for retry-safe clients.

Pattern: ^[A-Za-z0-9_\-]{8,255}$

Body

application/json

CreateWebhookEndpointDto

url

string<url>

required

event_categories

enum<string>[]

required

Minimum array length: 1

Available options:

onramp,

offramp,

conversion,

transfer,

deposit,

kyc

Response

Webhook endpoint created

status

enum<boolean>

required

Available options:

true

Example:

true

message

string

required

Human-readable summary

Example:

"Webhook endpoint created"

code

enum<string>

required

Available options:

ok

Example:

"ok"

data

object

required

Show child attributes