Skip to content
YusrDocs

API reference

Webhook endpoints

Register HTTPS endpoints to receive signed event notifications. Each mode (test and live) has its own endpoints and signing secrets.

Webhook endpoints endpoints
get/v1/webhooksList webhook endpoints
post/v1/webhooksCreate a webhook endpoint
get/v1/webhooks/{id}Retrieve a webhook endpoint
patch/v1/webhooks/{id}Update a webhook endpoint
DEL/v1/webhooks/{id}Delete a webhook endpoint
post/v1/webhooks/{id}/testSend a signed sample event
post/v1/webhooks/{id}/roll-secretRoll the signing secret

Read the Webhooks guide for the concepts behind these endpoints.

List webhook endpoints

get/v1/webhooks
curl "https://api.yusr.ng/v1/webhooks" \
  -H "Authorization: Bearer sk_test_..."

Responses

200Endpoints
Show response attributes
Response attributes
objectstringrequired

always "list"

dataarray of objectrequired
Show child attributes
idstringrequired
objectstringrequired

always "webhook_endpoint"

modestringrequired

One of test, live

urlstringrequired
eventsarray of stringrequired

One of transaction.paid, transaction.underpaid, transaction.overpaid, transaction.expired, transaction.late_payment, transaction.reversed, transaction.cancelled, settlement.completed

descriptionstring | nullrequired
enabledbooleanrequired
secretstring

Signing secret. Returned only on create.

disabled_reasonstring | nullrequired

Why the endpoint was disabled automatically, if it was.

failing_sincestring | nullrequired

When deliveries started failing continuously; null when healthy.

created_atstringrequired
has_morebooleanrequired
next_cursorstring | nullrequired
Response 200
{
  "object": "list",
  "data": [
    {
      "id": "whk_01JA9QF4H6K8M0P2R4T6V8X0Z2",
      "object": "webhook_endpoint",
      "mode": "live",
      "url": "https://acme.example.com/webhooks/yusr",
      "events": [
        "transaction.paid",
        "transaction.underpaid",
        "transaction.overpaid",
        "transaction.expired"
      ],
      "description": "Order fulfilment",
      "enabled": true,
      "disabled_reason": null,
      "failing_since": null,
      "created_at": "2026-10-06T13:20:05.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
Error responses
StatusMeaningError codes
401Authentication failedauthentication_failed
Try it in the sandbox

Create a webhook endpoint

post/v1/webhooks

The response includes the signing secret once. Live endpoints must use HTTPS and resolve to a public IP.

Headers

Headers
Idempotency-Keystring

Unique key (≤ 255 chars). Retrying with the same key and body within 24 h returns the original response.

max length 255

Request bodyapplication/json

Request body attributes
urlstring (uri)required

max length 2000

eventsarray of string

One of transaction.paid, transaction.underpaid, transaction.overpaid, transaction.expired, transaction.late_payment, transaction.reversed, transaction.cancelled, settlement.completed. min items 1

descriptionstring

max length 200

enabledboolean

default true

curl -X POST "https://api.yusr.ng/v1/webhooks" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://acme.example.com/webhooks/yusr",
  "events": [
    "transaction.paid",
    "transaction.underpaid",
    "transaction.overpaid",
    "transaction.expired"
  ],
  "description": "Order fulfilment"
}'

Responses

201Created
Show response attributes
Response attributes
idstringrequired
objectstringrequired

always "webhook_endpoint"

modestringrequired

One of test, live

urlstringrequired
eventsarray of stringrequired

One of transaction.paid, transaction.underpaid, transaction.overpaid, transaction.expired, transaction.late_payment, transaction.reversed, transaction.cancelled, settlement.completed

descriptionstring | nullrequired
enabledbooleanrequired
secretstring

Signing secret. Returned only on create.

disabled_reasonstring | nullrequired

Why the endpoint was disabled automatically, if it was.

failing_sincestring | nullrequired

When deliveries started failing continuously; null when healthy.

created_atstringrequired
Response 201
{
  "id": "whk_01JA9QF4H6K8M0P2R4T6V8X0Z2",
  "object": "webhook_endpoint",
  "mode": "live",
  "url": "https://acme.example.com/webhooks/yusr",
  "events": [
    "transaction.paid",
    "transaction.underpaid",
    "transaction.overpaid",
    "transaction.expired"
  ],
  "description": "Order fulfilment",
  "enabled": true,
  "disabled_reason": null,
  "failing_since": null,
  "created_at": "2026-10-06T13:20:05.000Z",
  "secret": "whsec_9fK2mQ7vX4pL8sT1wZ6yB3nD5hJ0cR2e"
}
Error responses
StatusMeaningError codes
400Invalid requestinvalid_request
401Authentication failedauthentication_failed
Try it in the sandbox

Retrieve a webhook endpoint

get/v1/webhooks/{id}

Path parameters

Path parameters
idstringrequired
curl "https://api.yusr.ng/v1/webhooks/whk_01JA9QF4H6K8M0P2R4T6V8X0Z2" \
  -H "Authorization: Bearer sk_test_..."

Responses

200Endpoint
Show response attributes
Response attributes
idstringrequired
objectstringrequired

always "webhook_endpoint"

modestringrequired

One of test, live

urlstringrequired
eventsarray of stringrequired

One of transaction.paid, transaction.underpaid, transaction.overpaid, transaction.expired, transaction.late_payment, transaction.reversed, transaction.cancelled, settlement.completed

descriptionstring | nullrequired
enabledbooleanrequired
secretstring

Signing secret. Returned only on create.

disabled_reasonstring | nullrequired

Why the endpoint was disabled automatically, if it was.

failing_sincestring | nullrequired

When deliveries started failing continuously; null when healthy.

created_atstringrequired
Response 200
{
  "id": "whk_01JA9QF4H6K8M0P2R4T6V8X0Z2",
  "object": "webhook_endpoint",
  "mode": "live",
  "url": "https://acme.example.com/webhooks/yusr",
  "events": [
    "transaction.paid",
    "transaction.underpaid",
    "transaction.overpaid",
    "transaction.expired"
  ],
  "description": "Order fulfilment",
  "enabled": true,
  "disabled_reason": null,
  "failing_since": null,
  "created_at": "2026-10-06T13:20:05.000Z"
}
Error responses
StatusMeaningError codes
401Authentication failedauthentication_failed
404Not foundnot_found
Try it in the sandbox

Update a webhook endpoint

patch/v1/webhooks/{id}

Path parameters

Path parameters
idstringrequired

Request bodyapplication/json

Request body attributes
urlstring (uri)

max length 2000

eventsarray of string

One of transaction.paid, transaction.underpaid, transaction.overpaid, transaction.expired, transaction.late_payment, transaction.reversed, transaction.cancelled, settlement.completed. min items 1

descriptionstring | null
enabledboolean
curl -X PATCH "https://api.yusr.ng/v1/webhooks/whk_01JA9QF4H6K8M0P2R4T6V8X0Z2" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": false
}'

Responses

200Updated
Show response attributes
Response attributes
idstringrequired
objectstringrequired

always "webhook_endpoint"

modestringrequired

One of test, live

urlstringrequired
eventsarray of stringrequired

One of transaction.paid, transaction.underpaid, transaction.overpaid, transaction.expired, transaction.late_payment, transaction.reversed, transaction.cancelled, settlement.completed

descriptionstring | nullrequired
enabledbooleanrequired
secretstring

Signing secret. Returned only on create.

disabled_reasonstring | nullrequired

Why the endpoint was disabled automatically, if it was.

failing_sincestring | nullrequired

When deliveries started failing continuously; null when healthy.

created_atstringrequired
Response 200
{
  "id": "whk_01JA9QF4H6K8M0P2R4T6V8X0Z2",
  "object": "webhook_endpoint",
  "mode": "live",
  "url": "https://acme.example.com/webhooks/yusr",
  "events": [
    "transaction.paid",
    "transaction.underpaid",
    "transaction.overpaid",
    "transaction.expired"
  ],
  "description": "Order fulfilment",
  "enabled": false,
  "disabled_reason": null,
  "failing_since": null,
  "created_at": "2026-10-06T13:20:05.000Z"
}
Error responses
StatusMeaningError codes
400Invalid requestinvalid_request
401Authentication failedauthentication_failed
404Not foundnot_found
Try it in the sandbox

Delete a webhook endpoint

DEL/v1/webhooks/{id}

Path parameters

Path parameters
idstringrequired
curl -X DELETE "https://api.yusr.ng/v1/webhooks/whk_01JA9QF4H6K8M0P2R4T6V8X0Z2" \
  -H "Authorization: Bearer sk_test_..."

Responses

200Deleted
Show response attributes
Response attributes
idstringrequired
objectstringrequired

always "webhook_endpoint"

deletedbooleanrequired

always true

Response 200
{
  "id": "whk_01JA9QF4H6K8M0P2R4T6V8X0Z2",
  "object": "webhook_endpoint",
  "deleted": true
}
Error responses
StatusMeaningError codes
401Authentication failedauthentication_failed
404Not foundnot_found
Try it in the sandbox

Send a signed sample event

post/v1/webhooks/{id}/test

Path parameters

Path parameters
idstringrequired
curl -X POST "https://api.yusr.ng/v1/webhooks/whk_01JA9QF4H6K8M0P2R4T6V8X0Z2/test" \
  -H "Authorization: Bearer sk_test_..."

Responses

200The delivery attempt, with the response your endpoint returned
Show response attributes
Response attributes
idstringrequired
objectstringrequired

always "webhook_delivery"

event_idstringrequired
event_typestring | nullrequired
endpoint_idstringrequired
urlstringrequired
attemptintegerrequired
statusstringrequired

One of pending, succeeded, failed

status_codeinteger | nullrequired
latency_msinteger | nullrequired
response_bodystring | nullrequired
errorstring | nullrequired
next_retry_atstring | nullrequired
delivered_atstring | nullrequired
is_testbooleanrequired
created_atstringrequired
updated_atstringrequired
Response 200
{
  "id": "whd_01JA9QG8K2M4P6R8T0V2X4Z6B8",
  "object": "webhook_delivery",
  "event_id": "evt_01JA9QG8J9W1Y3A5C7E9G1J3L5",
  "event_type": "transaction.paid",
  "endpoint_id": "whk_01JA9QF4H6K8M0P2R4T6V8X0Z2",
  "url": "https://acme.example.com/webhooks/yusr",
  "attempt": 1,
  "status": "succeeded",
  "status_code": 200,
  "latency_ms": 83,
  "response_body": "ok",
  "error": null,
  "next_retry_at": null,
  "delivered_at": "2026-10-06T13:21:40.029Z",
  "is_test": true,
  "created_at": "2026-10-06T13:21:39.862Z",
  "updated_at": "2026-10-06T13:21:40.031Z"
}
Error responses
StatusMeaningError codes
401Authentication failedauthentication_failed
404Not foundnot_found
Try it in the sandbox

Roll the signing secret

post/v1/webhooks/{id}/roll-secret

During the overlap (default 24 h, max 72 h) every delivery carries two signatures — one per secret — so you can deploy the new secret without dropping events.

Path parameters

Path parameters
idstringrequired

Request bodyapplication/json

Request body attributes
overlap_hoursinteger

0–72, default 24

curl -X POST "https://api.yusr.ng/v1/webhooks/whk_01JA9QF4H6K8M0P2R4T6V8X0Z2/roll-secret" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'

Responses

200New secret
Show response attributes
Response attributes
objectstringrequired

always "webhook_secret"

secretstringrequired

The new signing secret. Shown once.

previous_secret_expires_atstring | nullrequired

Until this time deliveries are signed with both the new and the previous secret.

Response 200
{
  "secret": "whsec_jw6FoEDzQ1XNRA6DHo32faj2Ww046xwP"
}
Error responses
StatusMeaningError codes
401Authentication failedauthentication_failed
404Not foundnot_found
Try it in the sandbox