Create a webhook endpoint

POST

/webhook-endpoints

const url = 'https://api.paywithnablr.com/v1/webhook-endpoints';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"url":"https://shop.example/webhooks/nablr","events":["payment.succeeded"],"active":true}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.paywithnablr.com/v1/webhook-endpoints \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "url": "https://shop.example/webhooks/nablr", "events": [ "payment.succeeded" ], "active": true }'

The response carries the endpoint’s signing secret (whsec_…). It is shown only here. Store it; you need it to check the Nablr-Signature header. The endpoint belongs to the key’s mode.

Authorizations

secretKey

Request Body^required

application/json

object

url

required

An absolute https URL on the public internet.

string format: uri

<= 2000 characters

Example

https://shop.example/webhooks/nablr

events

The events to send. Omitted or empty means every event.

Array<string>

Allowed values: payment.succeeded payment.failed payment.refunded payment_link.paid settlement.paid

active

boolean

default: true

Responses

201

The endpoint, with its secret.

application/json

object

data

required

object

required

string

object

required

string

Allowed value: webhook_endpoint

url

required

string

events

required

Array<string>

Allowed values: payment.succeeded payment.failed payment.refunded payment_link.paid settlement.paid

active

required

boolean

mode

required

string

Allowed values: test live

secret_last4

required

The end of the signing secret, to tell secrets apart.

string

created_at

required

string format: date-time

updated_at

required

string format: date-time

secret

required

The signing secret. Shown only in this response.

string

meta

required

object

request_id

required

This request’s id, also in the X-Request-Id header.

string

Example

{
  "data": {
    "id": "whe_01M3XX9QZ6J4B1M2N3P4Q5R6S7",
    "object": "webhook_endpoint",
    "url": "https://shop.example/webhooks/nablr",
    "events": [
      "payment.succeeded"
    ],
    "mode": "test",
    "secret_last4": "K1q4",
    "secret": "whsec_9xQ2vLk3TzN8bR4mW7pY1cF6hJ0sD5aE2gU8iO3nK1q"
  }
}

400

VALIDATION_FAILED: a field is wrong; details says which. MALFORMED_REQUEST: the body is not valid JSON.

application/json

object

error

required

object

message

required

A sentence for a person. Safe to show to your user.

string

code

required

string

Allowed values: VALIDATION_FAILED MALFORMED_REQUEST UNAUTHENTICATED INVALID_API_KEY SECRET_KEY_REQUIRED LIVE_MODE_NOT_ENABLED ACCOUNT_RESTRICTED TEST_MODE_ONLY NOT_FOUND CONFLICT DUPLICATE_REFERENCE IDEMPOTENCY_KEY_REUSED REQUEST_IN_PROGRESS INVALID_STATE_TRANSITION PAYLOAD_TOO_LARGE UNSUPPORTED_MEDIA_TYPE RATE_LIMITED INTERNAL_ERROR SERVICE_UNAVAILABLE

title

required

The code in words, for example Validation failed.

string

reference

A quotable reference for some failures.

string

details

One entry per field that is wrong.

Array<object>

object

field

required

string

code

required

For example required, invalid, format, length, unknown, type.

string

message

required

string

meta

Extra context, such as retry_after_seconds on RATE_LIMITED.

object

key

additional properties

any

meta

required

object

request_id

required

This request’s id, also in the X-Request-Id header.

string

Example

{
  "error": {
    "message": "Send a positive amount in minor units (500000 = ₦5,000.00).",
    "code": "VALIDATION_FAILED",
    "title": "Validation failed",
    "details": [
      {
        "field": "amount",
        "code": "invalid",
        "message": "Send a positive amount in minor units (500000 = ₦5,000.00)."
      }
    ]
  },
  "meta": {
    "request_id": "01a0fbd4-3b18-7181-9149-8dbcae100085"
  }
}

401

UNAUTHENTICATED: no Authorization: Bearer header. INVALID_API_KEY: the key is unknown, malformed or revoked.

application/json

object

error

required

object

message

required

A sentence for a person. Safe to show to your user.

string

code

required

string

title

required

The code in words, for example Validation failed.

string

reference

A quotable reference for some failures.

string

details

One entry per field that is wrong.

Array<object>

object

field

required

string

code

required

For example required, invalid, format, length, unknown, type.

string

message

required

string

meta

Extra context, such as retry_after_seconds on RATE_LIMITED.

object

key

additional properties

any

meta

required

object

request_id

required

This request’s id, also in the X-Request-Id header.

string

Example

{
  "error": {
    "message": "The API key provided is not valid.",
    "code": "INVALID_API_KEY",
    "title": "Invalid API key"
  },
  "meta": {
    "request_id": "01a0fbd4-3b68-75e0-bd33-0b950ddc99a5"
  }
}

403

SECRET_KEY_REQUIRED: you sent a publishable key. LIVE_MODE_NOT_ENABLED: a live key before your business is verified. ACCOUNT_RESTRICTED: the account is suspended.

application/json

object

error

required

object

message

required

A sentence for a person. Safe to show to your user.

string

code

required

string

title

required

The code in words, for example Validation failed.

string

reference

A quotable reference for some failures.

string

details

One entry per field that is wrong.

Array<object>

object

field

required

string

code

required

For example required, invalid, format, length, unknown, type.

string

message

required

string

meta

Extra context, such as retry_after_seconds on RATE_LIMITED.

object

key

additional properties

any

meta

required

object

request_id

required

This request’s id, also in the X-Request-Id header.

string

Example

{
  "error": {
    "message": "This request needs your secret key. Publishable keys can only be used from a checkout.",
    "code": "SECRET_KEY_REQUIRED",
    "title": "Secret key required"
  },
  "meta": {
    "request_id": "01a0fbd4-3b68-75e0-bd33-0b950ddc99a5"
  }
}

429

RATE_LIMITED: wait Retry-After seconds, then retry.

application/json

object

error

required

object

message

required

A sentence for a person. Safe to show to your user.

string

code

required

string

title

required

The code in words, for example Validation failed.

string

reference

A quotable reference for some failures.

string

details

One entry per field that is wrong.

Array<object>

object

field

required

string

code

required

For example required, invalid, format, length, unknown, type.

string

message

required

string

meta

Extra context, such as retry_after_seconds on RATE_LIMITED.

object

key

additional properties

any

meta

required

object

request_id

required

This request’s id, also in the X-Request-Id header.

string

Example

{
  "error": {
    "message": "Too many attempts. Please wait a moment and try again.",
    "code": "RATE_LIMITED",
    "title": "Rate limited",
    "meta": {
      "retry_after_seconds": 12
    }
  },
  "meta": {
    "request_id": "01a0fbd4-3b68-75e0-bd33-0b950ddc99a5"
  }
}

Headers

Retry-After

integer

Seconds to wait.

X-RateLimit-Reset

integer

Unix time when a request will be allowed again.

Create a webhook endpoint

Authorizations

Request Bodyrequired

Example

Responses

201

Example

400

Example

401

Example

403

Example

429

Example

Headers

Request Body^required