Skip to content

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:

ReasonMeaning
Repeated failuresrepeated_failuresDeliveries kept failing.
Gone 410gone_410Your endpoint answered 410 Gone.

Re-enable it with PATCH and enabled: true once your endpoint is healthy.

Code for Endpoints
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})`);}

Event types

EventWhen
Order acceptedorder.acceptedAn order was created and its amount held. Raised once for every order.
Order processingorder.processingAn order is in progress, and its amount stays held while it is delivered.
Order succeededorder.succeededAn order was delivered and its amount captured.
Order failedorder.failedAn order failed and its amount was released.
Order refundedorder.refundedA 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.under_reviewThe outcome of an order is being checked; its amount stays held.
Funding creditedfunding.creditedA funding was credited to the balance, a simulated one included. Raised once per funding.
Deposit confirmeddeposit.confirmedA 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.lowYour 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.recoveredYour 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:

HeaderWhat it holds
Webhook IDwebhook-idThe event id. The same on every retry and replay
Webhook timestampwebhook-timestampWhole seconds since the Unix epoch when this attempt was signed
Webhook signaturewebhook-signatureSpace-separated v1,<base64> signatures, each HMAC-SHA256 under the bytes of one secret (the base64 after whsec_) over <webhook-id>.<webhook-timestamp>.<raw body>

What your answer means:

Your answerWhat happens
2xx2XXReceived. Any 2xx counts as delivered: answer within 15 seconds and process afterwards
410410Gone. The endpoint is disabled and receives nothing more
Any otherAny otherA 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
Code for What arrives
An event
JSON
order.succeededSynthetic sandbox data
{  "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:

  1. 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.
  2. Answer quickly and do the work afterwards. A failed attempt is retried, and an endpoint that keeps failing is disabled with repeated_failures.
  3. An event can arrive more than once. Record the webhook-id, which is the event id, and ignore a repeat.
  4. Ignore an event type you do not handle; new ones will be added.
  5. Order events are ordered by the order's version, not by timestamp. Keep the highest version you have seen per order and ignore anything lower.
  6. Fetch the object before you release value to your own customer: GET /orders/{id} is the truth.
Code for Handling an event
Runs on your server, at the URL you registered
// 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:

  1. Take the bytes of your endpoint's secret: the base64 after whsec_, decoded. The secret's text is not the key.
  2. Compute an HMAC-SHA256 with those bytes over <webhook-id>.<webhook-timestamp>.<raw body>, and encode it in base64.
  3. The webhook-signature header holds one or more v1,<base64> values, separated by spaces. Accept the delivery when one of them equals yours, compared in constant time.
  4. Refuse a webhook-timestamp more than 5 minutes from your clock, so a captured delivery cannot be sent again later.

POST /webhook-endpoints/{id}/rotate-secret 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.

Code for Verifying a delivery
POST /v1/webhook-endpoints/{id}/rotate-secretSandbox, test key
// 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 /webhook-endpoints/{id}/test 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 an evt_ 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_00000000000000000000000000 for an order event, fnd_00000000000000000000000000 for funding.credited. Fetching it answers 404, so a receiver that fetches the object before it releases value releases nothing. A test order.failed carries status_reason provider_rejected, and a test order.under_review carries outcome_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_limited and a Retry-After. A type the endpoint does not subscribe to, or a disabled endpoint, is refused with invalid_request.
Code for Test events

Send a test event

POST /v1/webhook-endpoints/{id}/testSandbox, test key
// 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})`);}
The test event your endpoint receives
JSON
order.succeededSynthetic sandbox data
{  "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 /webhook-endpoints/{id}/deliveries 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.

NasfamYour endpointorder.succeededattempt 1 · event evt_1500failed · retried at next_attempt_atorder.succeededattempt 2 · the same event evt_1200succeeded · nothing more to sendEvery attempt is recorded. Record evt_1, ignore a repeat.
A failed attempt is retried with the same event id until your endpoint answers.

POST /webhook-deliveries/{id}/replay 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.

Code for Deliveries and replay

List webhook deliveries

GET /v1/webhook-endpoints/{id}/deliveriesSandbox, test key
// 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

POST /v1/webhook-deliveries/{id}/replaySandbox, test key
// 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.

Code for The event log
GET /v1/eventsSandbox, test key
// 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 in webhook-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-id and ignore one you have seen.
  • Ordering by timestamp. Keep the highest version you have seen for each order and ignore anything lower.
  • Acting on a test event. When test is true, answer 2xx and stop. Its order does not exist.