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
- 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 acceptshttpsonly. - NAS gives you a webhook secret. It is shown once. Store it in your secrets manager.
- Return a
2xxstatus as soon as you have saved the event. Do the slow work afterwards.
What an event looks like
Every event has the same envelope.
{
"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\"}"
}
| Field | Meaning |
|---|---|
id | Unique for each event. Use it to ignore repeats. |
eventType | The event name. See the catalogue. |
apiVersion | Always v3. |
createTime | When the event was created, in milliseconds since the epoch, as text. |
resource | A 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:
| Header | Value |
|---|---|
X-NAS-Signature-Timestamp | When NAS sent this attempt, in whole seconds since the epoch. Each retry carries its own. |
X-NAS-Signature | One 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:
- Read the raw body before your framework parses it. Re-encoding the JSON changes the bytes, and the signature then fails.
- 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.
- 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
v1value for each active secret. Your secret matches one of them. Accept the delivery if any value matches. v2values. NAS may add headers of its own to a delivery. When it does,X-NAS-Signature-Headerslists them and av2=value also covers them. Ignorev2values unless you read one of those headers. If you do, build the signed text asv2.<timestamp>., then each listed header asname:valueand a line feed, then one more line feed, then the body.- The compatibility headers. Each request also carries
Signature-Method(HMAC-SHA256),SignatureandTimestamp.Signatureis a Base64 HMAC-SHA256 of theresourcestring alone, andTimestampis in milliseconds. This pair covers onlyresource, so useX-NAS-Signaturefor new work.
Node.js
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
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.
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
2xxwithin 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
idand skip anidyou have already handled. - Do not rely on order. Events can arrive out of order. Use
createTimeand the state insideresource. - 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.
| Parameter | Meaning |
|---|---|
status | Only deliveries in this state: PENDING (waiting to be sent, or being retried), DELIVERED (your endpoint accepted it) or DEAD (it ran out of retries). |
limit | Items per page, from 1 to 500. The default is 100. |
before | Return 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"
{
"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
| Event | When it is sent |
|---|---|
CARD.UPDATED | The details of a card changed. |
CARD.DELETED | A card was deleted. |
CARD.SETTING.UPDATED | The payment mode of a card changed. |
CARD.SCENE.UPDATED | The transaction scenarios allowed on a card changed. |
CARD.BALANCE.NEGATIVE | A card balance went negative. |
CARD.3DS.OTP | A 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.CREATED | A card transaction was created, such as an authorisation. |
CARD_TRANSACTION.UPDATED | A card transaction changed, such as a settlement, refund or reversal. |
PHYSICAL_CARD.ACTIVATED | A physical card was activated. |
PHYSICAL_CARD.SHIPPING | Shipping information for a physical card is available or changed. |
PHYSICAL_CARD.VERIFY | A physical card needs the cardholder to be verified before activation. |
Cardholders
| Event | When it is sent |
|---|---|
CARDHOLDER.UPDATED | The details of a cardholder changed. |
CARDHOLDER.DELETED | A cardholder was deleted. |
Accounts and verification
| Event | When it is sent |
|---|---|
ACCOUNT.REGISTERED | An account was registered. |
KYC.UPDATED | The KYC verification status of an account changed. |
KYB.UPDATED | The KYB verification status of an account changed. |
ACCOUNT.DAILY.NEGATIVE | An account ended the day with a negative balance. Top it up to keep your cards working. |
Budgets
| Event | When it is sent |
|---|---|
BUDGET.CREATED | A budget was created. |
BUDGET.UPDATED | A budget changed. |
BUDGET.DELETED | A budget was deleted. |
BUDGET_TRANSACTION.CREATED | Money moved into or out of a budget. |
Wallet deposits
| Event | When it is sent |
|---|---|
BLOCKCHAIN_TRANSFER.UPDATE | A deposit to one of your wallets completed or changed state, including when a deposit is flagged as high risk and held. |
BLOCKCHAIN_TRANSFER.CREATED | A deposit to one of your wallets was detected. |
BLOCKCHAIN_REFUND.CREATED | A refund of a wallet deposit was created. |
BLOCKCHAIN_REFUND.UPDATE | A refund of a wallet deposit changed state. |
PROVIDER_FEES_CHANGED | The deposit fees that apply to your client changed. Read the new fees from the resource field. |
CRYPTO_ASSETS_BLOCKCHAIN_ADDRESS.UPDATED | A 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:
| Field | Meaning |
|---|---|
cardId, accountId | The card and the account. |
currency, amount | The purchase. |
cardNumber | A masked card number. |
otp | The one-time code. |
detail | What the purchase is for. |
expireTime | Seconds 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.