Webhooks
Be told when an order ends or money arrives, instead of polling.
Sandbox: test money only. No request moves real money.
Register an HTTPS endpoint and the events you want. Each event carries the full snapshot of the order, funding or deposit it is about, and each delivery is signed with your endpoint's secret. Every attempt to deliver it is recorded, a failed attempt is retried, and any delivery can be replayed. The same events are also in the event log for 30 days, so nothing is lost if your endpoint is down.
Availability: Available. Live and verified in production.
Endpoints
POST /webhook-endpoints takes an https:// URL of at most 2,048 characters, the list of event types (at least one, no duplicates) and an optional description of at most 200 characters. The answer includes the signing secret, shown once: store it now, it is not returned again. Update the URL, the events, the description or enabled with PATCH; delete with DELETE.
An address the API will not deliver to is refused with webhook_url_refused, and an endpoint past the most an account may hold with endpoint_limit.
An endpoint can be disabled by the API. enabled turns false and disabled_reason says why:
| Reason | Meaning |
|---|---|
| Repeated failuresrepeated_ | Deliveries kept failing. |
| Gone 410gone_ | Your endpoint answered 410 Gone. |
Re-enable it with PATCH and enabled: true once your endpoint is healthy.
// 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})`);}Event types
| Event | When |
|---|---|
| Order acceptedorder. | An order was created and its amount held. Raised once for every order. |
| Order processingorder. | An order is in progress, and its amount stays held while it is delivered. |
| Order succeededorder. | An order was delivered and its amount captured. |
| Order failedorder. | An order failed and its amount was released. |
| Order refundedorder. | A failed order's held amount was released back to available: nothing was taken, despite the name. The same change as order.failed, at the same version. |
| Order under revieworder. | The outcome of an order is being checked; its amount stays held. |
| Funding creditedfunding. | A funding was credited to the balance, a simulated one included. Raised once per funding. |
| Deposit confirmeddeposit. | A GRAM deposit was finalised on its network and a second source agreed. It is not credited yet: its status reads confirming until it is booked. |
| Balance lowbalance. | Your low-balance alert fired. It names the alert, its state and when, never an amount: read GET /balance for the figures. Sent only when you chose the webhook channel for that alert. |
| Balance recoveredbalance. | Your balance is back above the alert's threshold. The same three facts, and again no amount. |
New event types will be added. An endpoint receives only the types it subscribed to, but write your handler to ignore a type it does not know.
What arrives
Each event reaches your URL as a POST with the event as its JSON body. The event has an id, a type, a timestamp, an environment (sandbox or live), an api_version (v1) and data.object: the full snapshot of its subject at the time of the event. For an order event that is the order as GET /orders/{id} presents it, including status and version, and never a display name; for funding.credited it is the funding as GET /fundings presents it.
Three headers come with it:
| Header | What it holds |
|---|---|
| Webhook IDwebhook-id | The event id. The same on every retry and replay |
| Webhook timestampwebhook-timestamp | Whole seconds since the Unix epoch when this attempt was signed |
| Webhook signaturewebhook-signature | Space-separated v1,<base64> signatures, each HMAC-SHA256 under the bytes of one secret (the base64 after whsec_) over <webhook-id>. |
What your answer means:
| Your answer | What happens |
|---|---|
| 2xx2XX | Received. Any 2xx counts as delivered: answer within 15 seconds and process afterwards |
| 410410 | Gone. The endpoint is disabled and receives nothing more |
| Any otherAny other | A failure, 3xx included (redirects are never followed). Retried after 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 14 h, 20 h and 24 h, honouring Retry-After; then the endpoint is disabled |
{ "id": "evt_ 01K7SAMP000000000000000090", "type": "order. succeeded", "timestamp": "2026-10-10T10:15:05.000Z", "environment": "sandbox", "api_ version": "v1", "data": { "object": { "id": "ord_ 01K7SAMP000000000000000090", "environment": "sandbox", "status": "succeeded", "status_ reason": null, "product": "telegram_ stars", "selection": { "quantity": 50 }, "recipient": { "telegram_ username": "nasfam_ test_ ok" }, "amount": { "amount": 75, "currency": "USD" }, "quote_ id": null, "pricing_ version": "sandbox-synthetic-v1", "reference": "TEST-0001", "version": 2, "estimated_ completion_ at": "2026-10-10T10:15:05.000Z", "created_ at": "2026-10-10T10:15:02.000Z", "updated_ at": "2026-10-10T10:15:05.000Z", "completed_ at": "2026-10-10T10:15:05.000Z" } }}Handling an event
A receiver does six things, and the example does each in a few lines, in this order:
- Verify the signature over the raw body before you parse it, and refuse a timestamp more than 5 minutes from your clock. The next section shows how.
- Answer quickly and do the work afterwards. A failed attempt is retried, and an endpoint that keeps failing is disabled with
repeated_failures. - An event can arrive more than once. Record the
webhook-id, which is the eventid, and ignore a repeat. - Ignore an event type you do not handle; new ones will be added.
- Order events are ordered by the order's
version, not bytimestamp. Keep the highestversionyou have seen per order and ignore anything lower. - Fetch the object before you release value to your own customer:
GET /orders/{id}is the truth.
// Node. js 18 or later, no package. NASFAM_ WEBHOOK_ SECRET is the endpoint's whsec_ secret, read from the environment.import { createHmac, timingSafeEqual } from 'node:crypto';import { createServer } from 'node:http';const secret = Buffer. from( process. env. NASFAM_ WEBHOOK_ SECRET. slice( 'whsec_ '. length), 'base64'); // the secret's bytes, not its textconst handled = new Set(); // event ids already handled: use your databaseconst versions = new Map(); // the highest version seen per order// Standard Webhooks v1: one signature in the header is the HMAC of this body, and the timestamp is within 5 minutes.function verified( body, headers) { const header = ( name) => String( headers[name] ?? ''); const id = header( 'webhook-id'); const timestamp = header( 'webhook-timestamp'); if ( !id || !/ ^[0-9]+$/. test( timestamp) || Math. abs( Date. now() / 1000 - Number( timestamp)) > 300) return false; const expected = createHmac( 'sha256', secret). update( `${id}. ${timestamp}. `). update( body). digest(); return header( 'webhook-signature'). split( ' '). some(( signature) => { const [version, value = ''] = signature. split( ', '); const given = Buffer. from( value, 'base64'); return version === 'v1' && given. length === expected. length && timingSafeEqual( given, expected); });}createServer(( req, res) => { const chunks = []; req. on( 'data', ( chunk) => chunks. push( chunk)); req. on( 'end', () => { // Verify the raw body before you parse it: a body parsed and written again is not what was signed. const body = Buffer. concat( chunks); if ( !verified( body, req. headers)) { res. writeHead( 400). end(); return; } // Answer at once and do the work afterwards: a slow answer is retried. res. writeHead( 200). end(); const event = JSON. parse( body. toString( 'utf8')); // A test event is marked and its object is synthetic: acknowledge it and act on nothing. if ( event. test === true) { console. log( 'test', event. type, event. id); return; } // Retries and replays carry the same webhook-id, so the same event can arrive twice. if ( handled. has( event. id)) return; handled. add( event. id); // Ignore a type you do not handle: new ones will be added. if ( !event. type. startsWith( 'order. ')) return; // Order events are ordered by version, never by timestamp. const order = event. data. object; if ( order. version <= ( versions. get( order. id) ?? 0)) return; versions. set( order. id, order. version); // Fetch the order with GET / orders/ {id} before you release value to your customer. console. log( event. type, order. id, order. status); });}). listen( Number( process. env. PORT ?? 3000));Verifying a delivery
Careful. Verify the signature over the raw body, exactly as it arrived, before you parse it. A body parsed and written out again is not the bytes that were signed, and the check fails.
The signing scheme is Standard Webhooks v1. To check a delivery:
- Take the bytes of your endpoint's secret: the base64 after
whsec_, decoded. The secret's text is not the key. - Compute an HMAC-SHA256 with those bytes over
<webhook-id>., and encode it in base64.<webhook-timestamp>. <raw body> - The
webhook-signatureheader holds one or morev1,<base64>values, separated by spaces. Accept the delivery when one of them equals yours, compared in constant time. - Refuse a
webhook-timestampmore than 5 minutes from your clock, so a captured delivery cannot be sent again later.
POST / issues a new secret and returns it once. For the 24 hours after a rotation both secrets sign, and the header carries one signature for each, so a verifier that holds both changes over without a gap.
// npm install axiosimport axios from 'axios';try { const { status, data: endpoint } = await axios. post( 'https:// sandbox-api. nasfampay. com/ v1/ webhook-endpoints/ whe_ 01K7SAMP000000000000000090/ rotate-secret', null, { 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})`);}Test events
POST / with a type the endpoint subscribes to sends it one test event. It is signed with the endpoint's secrets, delivered, retried and listed in its deliveries exactly as a real event is, so your verification is proved before a real order. Each request sends one; it takes no Idempotency-Key.
- It is marked. Its envelope says
"test": true, and its id is anevt_id dated 1970-01-01 (evt_0000000000...), which no real event has. - Its object is synthetic. It has the shape of the type's real object, with the all-zero id:
ord_00000000000000000000000000for an order event,fnd_00000000000000000000000000forfunding.credited. Fetching it answers 404, so a receiver that fetches the object before it releases value releases nothing. A testorder.failedcarriesstatus_reasonprovider_rejected, and a testorder.under_reviewcarriesoutcome_unconfirmed. - It changes nothing. It is not in the event log, reaches no other endpoint and creates no order, funding or balance movement.
- It is bounded. An endpoint takes at most 20 test events in any hour; the next is refused with
rate_limitedand aRetry-After. A type the endpoint does not subscribe to, or a disabled endpoint, is refused withinvalid_request.
Send a test event
// npm install axiosimport axios from 'axios';try { const { status, data: delivery } = await axios. post( 'https:// sandbox-api. nasfampay. com/ v1/ webhook-endpoints/ whe_ 01K7SAMP000000000000000090/ test', { type: 'order. succeeded' }, { headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, }, }, ); console. log( status, delivery);} 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})`);}{ "id": "evt_ 0000000000K7SAMP0000000090", "type": "order. succeeded", "timestamp": "2026-10-10T10:13:00.000Z", "environment": "sandbox", "api_ version": "v1", "data": { "object": { "id": "ord_ 00000000000000000000000000", "environment": "sandbox", "status": "succeeded", "status_ reason": null, "product": "telegram_ stars", "selection": { "quantity": 50 }, "recipient": { "telegram_ username": "nasfam_ test_ ok" }, "amount": { "amount": 75, "currency": "USD" }, "quote_ id": null, "pricing_ version": "sandbox-synthetic-v1", "reference": "TEST-0001", "version": 2, "estimated_ completion_ at": "2026-10-10T10:15:05.000Z", "created_ at": "2026-10-10T10:15:02.000Z", "updated_ at": "2026-10-10T10:15:05.000Z", "completed_ at": "2026-10-10T10:15:05.000Z" } }, "test": true}Deliveries and replay
GET / lists every attempt, newest first: the event_id, the attempt number, its status (pending, succeeded, failed or abandoned), your endpoint's response_status, the duration_ms and, for a failed attempt, next_attempt_at.
POST / sends the same event again, with the same webhook-id and body and a new timestamp and signature, and answers 202 with the scheduled delivery. A replay never creates a financial event: it is safe to use after an outage, and your handler should treat it like any repeat.
List webhook deliveries
// npm install axiosimport axios from 'axios';try { const { status, data: deliveries } = await axios. get( 'https:// sandbox-api. nasfampay. com/ v1/ webhook-endpoints/ whe_ 01K7SAMP000000000000000090/ deliveries', { headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, }, }, ); console. log( status, deliveries);} 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})`);}Replay a webhook delivery
// npm install axiosimport axios from 'axios';try { const { status, data: delivery } = await axios. post( 'https:// sandbox-api. nasfampay. com/ v1/ webhook-deliveries/ whd_ 01K7SAMP000000000000000090/ replay', null, { headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, }, }, ); console. log( status, delivery);} 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})`);}The event log
GET /events lists every event of the last 30 days, newest first, with type as a filter; GET /events/{id} returns one. Use it to catch up after downtime or to reconcile what your endpoint received. Test events are not in it.
// npm install axiosimport axios from 'axios';try { const { status, data: events } = await axios. get( 'https:// sandbox-api. nasfampay. com/ v1/ events', { params: { type: 'order. succeeded' }, headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, }, }, ); console. log( status, events);} 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})`);}Not defined by the contract
- The most endpoints an account may register. You are told when you reach it, with
endpoint_limit. - How long the record of each delivery is kept.
Common mistakes
- Verifying a parsed body. Verify the raw bytes, then parse. A body written out again does not match its signature.
- Comparing signatures with
==. Compare in constant time, and accept any one of the values inwebhook-signature. - Doing the work before answering. Answer within 15 seconds, then work. A slow endpoint looks like a failing one.
- Acting on the same event twice. Keep the
webhook-idand ignore one you have seen. - Ordering by
timestamp. Keep the highestversionyou have seen for each order and ignore anything lower. - Acting on a test event. When
testis true, answer 2xx and stop. Its order does not exist.
Related guides
- Testing webhooks: a test event, a failure on purpose, a repeat and a replay.
- Create a webhook endpoint: every field of the request.
- Send a test event: every field of the request.
- Handle responses and webhooks: the event in the journey of one order.
- Idempotency and safe retries: why a repeat is expected.
