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
| Header | Value | Sent |
|---|---|---|
Authorization | Bearer nbk_test_... | Required |
Content-Type | application/json | Required |
Idempotency-Key | 3f1c9a52-7d4e-4b8a-9c21-5e6f7a8b9c0d | Optional |
Parameters
| Field | Description |
|---|---|
| Idempotency keyIdempotency-Key · header string | Bound 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.
| Field | Description |
|---|---|
| URLurl · string · required | Format uri. Pattern ^https://. Up to 2048 characters. |
| Eventsevents · array of EventType · required | At 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 · string | Pattern ^[^\u0000\uD800-\uDFFF]*$. Up to 200 characters. |
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);// 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
| Status | Meaning | Body |
|---|---|---|
| OK200 | A 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 |
| Created201 | Created. 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 large413 | The request body is over 16 KB (payload_too_large). Refused before authentication; nothing is read further. Headers: Request-Id. | Problem object |
| Too many requests429 | Too 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 statusdefault | Error (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
| Field | Description |
|---|---|
| IDid · string · required | Pattern ^whe_[0-9A-HJKMNP-TV-Z]{26}$. |
| URLurl · string · required | |
| Eventsevents · array of EventType · required | 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 · string or null | |
| Enabledenabled · boolean · required | |
| Disabled reasondisabled_ | Known values: repeated_failures, gone_410. |
| Created atcreated_ | Format date-time. |
Responses are extensible: ignore fields, enum values and event types you do not know. Any other status is a Problem (see Errors).
{ "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"}{ "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"}{ "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 | |
|---|---|
| Authentication | Your key as a bearer token in the Authorization header: a nbk_test_ key on the sandbox host. |
| Idempotency | Optional. Sent, it is bound permanently to what the first request made, and a retry repeats nothing. |
| In the sandbox | Delivers your sandbox events to your URL, signed as Live events are. |
| On Live | The same request, on the Live host with a live key, which exists only for a workspace activated for Live. See Go live. |
| Funding | None. This request does not touch your balance. |
| Status changes | The endpoint starts enabled. |
| Webhook events | None. |
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.
