Skip to content

Create webhook endpoint

POST/webhook-endpoints

Create a webhook endpoint (the secret is returned once).

Sandbox: test money only. No request moves real money.

Authenticate with your sandbox key as a bearer token: Authorization: Bearer nbk_test_....

Note. The answer carries the endpoint's signing secret, shown once: store it now. A replay with the same Idempotency-Key never returns it. Verifying a delivery shows how a receiver checks a signature with it.

Request

HeaderValueSent
AuthorizationBearer nbk_test_...Required
Content-Typeapplication/jsonRequired
Idempotency-Key3f1c9a52-7d4e-4b8a-9c21-5e6f7a8b9c0dOptional

Parameters

FieldDescription
Idempotency keyIdempotency-Key · header stringBound permanently, in the database, to what the first request made (a quote, an endpoint, a rotation, a delivery replay), as a money operation's key is: a retry with the same key and request answers 200 with Idempotent-Replayed: true and repeats nothing, and the same key with another request or on another operation is 422 idempotency_key_reused. A replay never returns a secret. Without a key, every request is performed. Pattern ^[A-Za-z0-9_-]{16,64}$.

Body

Unknown fields are rejected.

FieldDescription
URLurl · string · requiredFormat uri. Pattern ^https://. Up to 2048 characters.
Eventsevents · array of EventType · requiredAt least 1 item. No duplicates. Each one of order.accepted, order.processing, order.succeeded, order.failed, order.refunded, order.under_review, funding.credited, deposit.confirmed, balance.low, balance.recovered.
Descriptiondescription · stringPattern ^[^\u0000\uD800-\uDFFF]*$. Up to 200 characters.
The request in cURL, JavaScript and Python
POST /v1/webhook-endpointsSandbox, test key
const response = await fetch('https://sandbox-api.nasfampay.com/v1/webhook-endpoints', {  method: 'POST',  headers: {    Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,    'Content-Type': 'application/json',  },  body: JSON.stringify({    url: 'https://example.com/webhooks/nasfam',    events: ['order.accepted'],  }),});if (!response.ok) {  const problem = await response.json();  throw new Error(`${problem.status} ${problem.code}: ${problem.title} (request ${problem.request_id})`);}const result = await response.json();console.log(response.status, result);
Code for Request
POST /v1/webhook-endpointsSandbox, test key
// npm install axiosimport axios from 'axios';try {  const { status, data: endpoint } = await axios.post(    'https://sandbox-api.nasfampay.com/v1/webhook-endpoints',    {      url: 'https://example.com/webhooks/nasfam',      events: [        'order.succeeded',        'order.failed',        'order.under_review',        'funding.credited',      ],      description: 'Order updates',    },    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,      },    },  );  console.log(status, endpoint);} catch (error) {  if (!axios.isAxiosError(error) || !error.response) throw error;  const problem = error.response.data;  throw new Error(`${problem.status} ${problem.code}: ${problem.title} (request ${problem.request_id})`);}

Responses

StatusMeaningBody
OK200A replay of an earlier request with the same Idempotency-Key: the endpoint it made, as it is now, and no secret, which is shown in the 201 only. Nothing is created again. Headers: RateLimit (draft-ietf-httpapi-ratelimit-headers-11. the same buckets, each "<bucket>";r=<whole requests remaining, never negative>;t=<seconds until the quota is fully available again>. ), RateLimit-Policy (draft-ietf-httpapi-ratelimit-headers-11. a structured field list with one item per bucket the request drew on (orders, quotes, quotes_daily, reads, webhooks, lookups, lookups_org, lookups_daily), each "<bucket>";q=<quota>;w=<window seconds>. no partition key (pk) is sent. ), Idempotent-Replayed.WebhookEndpoint object
Created201Created. Headers: RateLimit (draft-ietf-httpapi-ratelimit-headers-11. the same buckets, each "<bucket>";r=<whole requests remaining, never negative>;t=<seconds until the quota is fully available again>. ), RateLimit-Policy (draft-ietf-httpapi-ratelimit-headers-11. a structured field list with one item per bucket the request drew on (orders, quotes, quotes_daily, reads, webhooks, lookups, lookups_org, lookups_daily), each "<bucket>";q=<quota>;w=<window seconds>. no partition key (pk) is sent. ).WebhookEndpointWithSecret object
Content too large413The request body is over 16 KB (payload_too_large). Refused before authentication; nothing is read further. Headers: Request-Id.Problem object
Too many requests429Too many requests (rate_limited), or your queued orders are at your cap (queue_limit). A bucket that cannot be read at once because of contention is answered here too, never waited on. Honour Retry-After. . Headers: Request-Id, Retry-After (seconds to wait before retrying), RateLimit (draft-ietf-httpapi-ratelimit-headers-11. the same buckets, each "<bucket>";r=<whole requests remaining, never negative>;t=<seconds until the quota is fully available again>. ), RateLimit-Policy (draft-ietf-httpapi-ratelimit-headers-11. a structured field list with one item per bucket the request drew on (orders, quotes, quotes_daily, reads, webhooks, lookups, lookups_org, lookups_daily), each "<bucket>";q=<quota>;w=<window seconds>. no partition key (pk) is sent. ).Problem object
Any other statusdefaultError (RFC 9457). A 503 service_unavailable with Retry-After means the request was not processed: the rate limiter or the database could not answer, and the API refuses rather than serve unlimited (reads included). For a money-moving operation, retrying with the same Idempotency-Key is always safe. . Headers: Request-Id, Retry-After (on 429 and some 503 responses).Problem object

The webhook endpoint object

FieldDescription
IDid · string · requiredPattern ^whe_[0-9A-HJKMNP-TV-Z]{26}$.
URLurl · string · required
Eventsevents · array of EventType · requiredEach one of order.accepted, order.processing, order.succeeded, order.failed, order.refunded, order.under_review, funding.credited, deposit.confirmed, balance.low, balance.recovered.
Descriptiondescription · string or null
Enabledenabled · boolean · required
Disabled reasondisabled_reason · string or nullKnown values: repeated_failures, gone_410.
Created atcreated_at · string · requiredFormat date-time.

Responses are extensible: ignore fields, enum values and event types you do not know. Any other status is a Problem (see Errors).

Every kind of response
201 CreatedSynthetic sandbox data
{  "secret": "whsec_EXAMPLExNOTxAxSECRETxEXAMPLExNOTxAxSECRETxEXAMPL",  "id": "whe_01K7SAMP000000000000000001",  "url": "https://example.com/webhooks/nasfam",  "events": [    "order.accepted"  ],  "description": null,  "enabled": true,  "disabled_reason": null,  "created_at": "2026-10-10T10:05:02Z"}
Code for Responses
Response
JSON
201 CreatedSynthetic sandbox data
{  "id": "whe_01K7SAMP000000000000000090",  "url": "https://example.com/webhooks/nasfam",  "events": [    "order.succeeded",    "order.failed",    "order.under_review",    "funding.credited"  ],  "description": "Order updates",  "enabled": true,  "disabled_reason": null,  "created_at": "2026-10-10T10:12:00.000Z",  "secret": "whsec_EXAMPLExNOTxAxSECRETxEXAMPLExNOTxAxSECRETxEXAMPL"}
Error
JSON
429 Too Many RequestsSynthetic sandbox data
{  "type": "about:blank",  "title": "Too many requests",  "status": 429,  "code": "rate_limited",  "category": "rate_limit",  "detail": "Too many requests. Retry after the time in Retry-After.",  "param": null,  "request_id": "req_01K7SAMP000000000000000090"}

How it behaves

What to expect
AuthenticationYour key as a bearer token in the Authorization header: a nbk_test_ key on the sandbox host.
IdempotencyOptional. Sent, it is bound permanently to what the first request made, and a retry repeats nothing.
In the sandboxDelivers your sandbox events to your URL, signed as Live events are.
On LiveThe same request, on the Live host with a live key, which exists only for a workspace activated for Live. See Go live.
FundingNone. This request does not touch your balance.
Status changesThe endpoint starts enabled.
Webhook eventsNone.

Error responses

This operation can also answer with webhook_url_refused, endpoint_limit, idempotency_key_reused, payload_too_large, unknown_field.

Any request can answer with invalid_request, invalid_api_key, key_expired, key_environment_mismatch, insufficient_scope, rate_limited, service_unavailable, internal_error. Errors says what to do about each one.