Skip to main content

Webhooks

NAS sends an HTTP POST to your callback URL whenever something changes: a card transaction, a KYC result, a deposit, a shipment. Use webhooks to keep your records current instead of polling.

Set up​

  1. Send NAS the https URL of your endpoint. NAS registers it for your client. The sandbox also accepts http, so you can test against a local tunnel. Production accepts https only.
  2. NAS gives you a webhook secret. It is shown once. Store it in your secrets manager.
  3. Return a 2xx status as soon as you have saved the event. Do the slow work afterwards.

What an event looks like​

Every event has the same envelope.

Webhook CARD_TRANSACTION.CREATED
{
"id": "6a94b9c7-40d6-4007-a5d0-a96d714a1108",
"eventType": "CARD_TRANSACTION.CREATED",
"apiVersion": "v3",
"code": "000000",
"message": "",
"createTime": "1757649535314",
"resource": "{\"cardId\":\"d8eda079-6ba7-409e-99c8-ab5f83566fbd\",\"amount\":\"5\",\"status\":\"PENDING\"}"
}
FieldMeaning
idUnique for each event. Use it to ignore repeats.
eventTypeThe event name. See the catalogue.
apiVersionAlways v3.
createTimeWhen the event was created, in milliseconds since the epoch, as text.
resourceA JSON document, carried as a string. Parse it a second time. Its fields depend on the event type.

Verify every delivery​

Check the signature before you trust anything in the body. Anyone who knows your URL can send it a fake event.

Each request carries these headers:

HeaderValue
X-NAS-Signature-TimestampWhen NAS sent this attempt, in whole seconds since the epoch. Each retry carries its own.
X-NAS-SignatureOne or more signatures, separated by commas. Each looks like v1= followed by 64 hex digits.

The v1 signature is a hex HMAC-SHA256, keyed with your webhook secret, over the timestamp, a dot, and the exact bytes of the request body:

HMAC-SHA256(secret, "<X-NAS-Signature-Timestamp>" + "." + <raw body bytes>)

To verify a delivery:

  1. Read the raw body before your framework parses it. Re-encoding the JSON changes the bytes, and the signature then fails.
  2. We recommend that you reject a delivery whose timestamp is more than 300 seconds from your clock, in either direction. This is your own replay protection, not a NAS rule. It stops a captured event being sent again later.
  3. Compute the signature with your secret and compare it with each v1= value, using a constant-time comparison. Accept the delivery if one matches.

Notes:

  • Several values. While NAS rotates your secret, the header holds one v1 value for each active secret. Your secret matches one of them. Accept the delivery if any value matches.
  • v2 values. NAS may add headers of its own to a delivery. When it does, X-NAS-Signature-Headers lists them and a v2= value also covers them. Ignore v2 values unless you read one of those headers. If you do, build the signed text as v2.<timestamp>., then each listed header as name:value and a line feed, then one more line feed, then the body.
  • The compatibility headers. Each request also carries Signature-Method (HMAC-SHA256), Signature and Timestamp. Signature is a Base64 HMAC-SHA256 of the resource string alone, and Timestamp is in milliseconds. This pair covers only resource, so use X-NAS-Signature for new work.

Node.js​

verify.mjs
import { createHmac, timingSafeEqual } from 'node:crypto';

const TOLERANCE_SECONDS = 300;

// rawBody: Buffer with the exact bytes received.
// timestamp: the X-NAS-Signature-Timestamp header.
// signature: the X-NAS-Signature header.
// secret: your webhook secret.
export function verifyNasSignature({ rawBody, timestamp, signature, secret, now = Date.now() / 1000 }) {
if (typeof timestamp !== 'string' || !/^\d{1,12}$/.test(timestamp) || typeof signature !== 'string') return false;
if (Math.abs(now - Number(timestamp)) > TOLERANCE_SECONDS) return false;

const expected = createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest();

return signature
.split(',')
.map((value) => value.trim())
.filter((value) => value.startsWith('v1='))
.some((value) => {
const received = Buffer.from(value.slice(3), 'hex');
return received.length === expected.length && timingSafeEqual(received, expected);
});
}

Python​

verify.py
import hashlib
import hmac
import re
import time

TOLERANCE_SECONDS = 300


def verify_nas_signature(raw_body: bytes, timestamp: str, signature: str, secret: str, now: float | None = None) -> bool:
"""raw_body: the exact bytes received.
timestamp: the X-NAS-Signature-Timestamp header.
signature: the X-NAS-Signature header.
secret: your webhook secret.
"""
if not timestamp or not signature or not re.fullmatch(r"\d{1,12}", timestamp):
return False
now = time.time() if now is None else now
if abs(now - int(timestamp)) > TOLERANCE_SECONDS:
return False

signed = timestamp.encode("ascii") + b"." + raw_body
expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest().encode("ascii")

for value in signature.split(","):
value = value.strip()
if value.startswith("v1=") and hmac.compare_digest(value[3:].encode("utf-8"), expected):
return True
return False

Java​

This sample needs Java 17 or later.

NasWebhook.java
import java.nio.charset.StandardCharsets;
import java.security.GeneralSecurityException;
import java.security.MessageDigest;
import java.util.HexFormat;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public final class NasWebhook {
private static final long TOLERANCE_SECONDS = 300;

private NasWebhook() {
}

/**
* rawBody: the exact bytes received.
* timestamp: the X-NAS-Signature-Timestamp header.
* signature: the X-NAS-Signature header.
* secret: your webhook secret.
*/
public static boolean verify(byte[] rawBody, String timestamp, String signature, String secret, long nowSeconds) {
if (timestamp == null || signature == null || !timestamp.matches("\\d{1,12}")) {
return false;
}
if (Math.abs(nowSeconds - Long.parseLong(timestamp)) > TOLERANCE_SECONDS) {
return false;
}
try {
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
mac.update((timestamp + ".").getBytes(StandardCharsets.US_ASCII));
byte[] expected = mac.doFinal(rawBody);

for (String part : signature.split(",")) {
String value = part.trim();
if (!value.startsWith("v1=")) {
continue;
}
byte[] received;
try {
received = HexFormat.of().parseHex(value.substring(3));
} catch (IllegalArgumentException notHex) {
continue;
}
if (MessageDigest.isEqual(received, expected)) {
return true;
}
}
return false;
} catch (GeneralSecurityException e) {
throw new IllegalStateException(e);
}
}
}

These three samples are run in NAS's checks against signatures made by NAS's own signing code, including a rotation case, a changed body and a stale timestamp.

Handle deliveries​

  • Answer fast. Return a 2xx within 10 seconds. Any other answer, a timeout or no answer counts as a failure.
  • Expect repeats. The same event can arrive more than once. Save each id and skip an id you have already handled.
  • Do not rely on order. Events can arrive out of order. Use createTime and the state inside resource.
  • Never log secrets. Do not log the webhook secret. Do not log the one-time codes in CARD.3DS.OTP.

Retries​

If a delivery fails, NAS tries again with a growing pause. There are up to 8 attempts, starting with a 10 second pause that doubles each time up to 10 minutes. The whole run lasts about 20 minutes. Each attempt is signed afresh with its own timestamp.

While an event for one card is being retried, later events for the same card wait behind it.

If every attempt fails, NAS stops and records the delivery as DEAD. A dead event is not sent again by itself, and the card's later events carry on. A gap like this can leave your records behind. Read the object again (the transaction, the card, the account) to catch up.

Check delivery status​

List webhook deliveries shows how each event sent to your webhook URL went, newest first. You see only your own deliveries, and never the payloads. Use it to find gaps after an outage.

ParameterMeaning
statusOnly deliveries in this state: PENDING (waiting to be sent, or being retried), DELIVERED (your endpoint accepted it) or DEAD (it ran out of retries).
limitItems per page, from 1 to 500. The default is 100.
beforeReturn only deliveries with an id lower than this. Send the nextBefore of the previous page.
curl "https://sandbox-api.nas.cards/open-api/v3/broker/deliveries?status=DEAD&limit=50" \
-H "x-access-token: $ACCESS_TOKEN"
Response GET /open-api/v3/broker/deliveries
{
"code": "000000",
"message": "success",
"data": {
"deadLettered": 1,
"pending": 0,
"deliveries": [
{
"id": 4812,
"eventId": "6c1b0e0a-6d2f-4f0e-9a52-0d4c3b8f7a11",
"eventType": "CARD.UPDATED",
"status": "DEAD",
"attempts": 8,
"lastError": "endpoint answered 500",
"createdAt": "2026-11-05T09:12:44.512Z",
"deliveredAt": null
}
],
"nextBefore": null
}
}

deadLettered and pending count all your deliveries in those states, whatever the filter. When nextBefore is not null, send it as before to read the next, older page. Only NAS can send a dead delivery again. Contact NAS support and quote the delivery id.

Event catalogue​

Each event name links to its reference page, which shows an example.

Cards​

EventWhen it is sent
CARD.UPDATEDThe details of a card changed.
CARD.DELETEDA card was deleted.
CARD.SETTING.UPDATEDThe payment mode of a card changed.
CARD.SCENE.UPDATEDThe transaction scenarios allowed on a card changed.
CARD.BALANCE.NEGATIVEA card balance went negative.
CARD.3DS.OTPA card payment needs a one-time code for 3-D Secure verification. The payload carries the card, the amount and the code. Show or forward the code to the cardholder promptly; it is kept only as long as delivery needs it.
CARD_TRANSACTION.CREATEDA card transaction was created, such as an authorisation.
CARD_TRANSACTION.UPDATEDA card transaction changed, such as a settlement, refund or reversal.
PHYSICAL_CARD.ACTIVATEDA physical card was activated.
PHYSICAL_CARD.SHIPPINGShipping information for a physical card is available or changed.
PHYSICAL_CARD.VERIFYA physical card needs the cardholder to be verified before activation.

Cardholders​

EventWhen it is sent
CARDHOLDER.UPDATEDThe details of a cardholder changed.
CARDHOLDER.DELETEDA cardholder was deleted.

Accounts and verification​

EventWhen it is sent
ACCOUNT.REGISTEREDAn account was registered.
KYC.UPDATEDThe KYC verification status of an account changed.
KYB.UPDATEDThe KYB verification status of an account changed.
ACCOUNT.DAILY.NEGATIVEAn account ended the day with a negative balance. Top it up to keep your cards working.

Budgets​

EventWhen it is sent
BUDGET.CREATEDA budget was created.
BUDGET.UPDATEDA budget changed.
BUDGET.DELETEDA budget was deleted.
BUDGET_TRANSACTION.CREATEDMoney moved into or out of a budget.

Wallet deposits​

EventWhen it is sent
BLOCKCHAIN_TRANSFER.UPDATEA deposit to one of your wallets completed or changed state, including when a deposit is flagged as high risk and held.
BLOCKCHAIN_TRANSFER.CREATEDA deposit to one of your wallets was detected.
BLOCKCHAIN_REFUND.CREATEDA refund of a wallet deposit was created.
BLOCKCHAIN_REFUND.UPDATEA refund of a wallet deposit changed state.
PROVIDER_FEES_CHANGEDThe deposit fees that apply to your client changed. Read the new fees from the resource field.
CRYPTO_ASSETS_BLOCKCHAIN_ADDRESS.UPDATEDA deposit address was frozen, or a deposit to it was put on hold. Create a new deposit address before the next deposit.

3-D Secure codes​

CARD.3DS.OTP is sent when a purchase needs a one-time code. The resource holds:

FieldMeaning
cardId, accountIdThe card and the account.
currency, amountThe purchase.
cardNumberA masked card number.
otpThe one-time code.
detailWhat the purchase is for.
expireTimeSeconds until the code stops working.

Pass the code to the cardholder at once, in your app or by message. It is valid for only a few minutes. Do not store it and do not write it to logs. NAS removes the code from its own records after the delivery is final, and in any case within a day.

Test webhooks in the sandbox​

Register a sandbox callback URL with NAS. The sandbox accepts http, so a local tunnel works. Events are sent for what you do in the sandbox, for example when you run a simulator. See Sandbox testing.

Treat each event type you rely on as unproven until you have seen it arrive at your endpoint. The going live checklist asks you to confirm this.