Webhooks
Signed events for every charge, payout, payment, mandate and top-up - payloads, signature checks in Node and Python, retries.
Set a webhook URL on your partner record (https, a public host name) and USD.NET POSTs an event to it within a second of each block that concerns you.
Events
type | When |
|---|---|
charge.succeeded / charge.failed | A charge from your server wallet was sealed or refused by the block |
payout.succeeded / payout.failed | A payout from your server wallet |
payment.received | A user (or anyone) transferred USD₮ to one of your server wallets, e.g. USDNet.pay |
transfer.sent | A transfer from one of your server wallets (a sweep, a bridge withdrawal) |
mandate.created | A user gave one of your server wallets a mandate (or replaced one) |
mandate.revoked | A user revoked it |
user.credited | USD₮ arrived in the account of a user whose mandate lets you read it: a deposit, a transfer, a payout from someone else |
ping | Send test event in usd.net/wallet/business |
Payload
{
"id": "evt_6f1c9b2a40de8e7f3a1c55b2",
"type": "charge.succeeded",
"created": 1762268401234,
"network": "mainnet",
"chain": "usdnet-1",
"partner": "pt_4b8d526f30e5",
"data": {
"hash": "0x9a…", "type": "charge", "status": "final",
"from": "0x7c1e…40ab", "to": "0x5b2f…91c0", "user": "0x7c1e…40ab",
"amount": "4.99", "fee": "0.01", "id": "order_1042", "memo": "Booster pack",
"block": 18230, "time": 1762268401100
}
}data holds the transaction (hash, type, status, from, to, amount, fee, memo, id, block, time, error), user (the other side), and mandate on mandate events. Headers:
| Header | Value |
|---|---|
usdnet-signature | t=<unix seconds>,v1=<hex HMAC-SHA256> |
usdnet-event | The event type |
usdnet-delivery | The event id, the same on every retry |
user-agent | USD.NET-Webhooks/1 |
Check the signature
The signature is an HMAC-SHA256, keyed with your webhook secret (whsec_…), of "<t>.<raw body>". Check it against the raw body, before parsing, and reject timestamps more than 5 minutes off.
const event = await USDNet.verifyWebhook(rawBody, req.headers['usdnet-signature'], process.env.USDNET_WEBHOOK_SECRET);import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(raw, header, secret) {
const [, t, v1] = /t=(\d+),v1=([0-9a-f]{64})/.exec(header || '') || [];
if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) throw new Error('stale');
const mac = createHmac('sha256', secret).update(`${t}.${raw}`).digest();
if (!timingSafeEqual(mac, Buffer.from(v1, 'hex'))) throw new Error('bad signature');
return JSON.parse(raw);
}import hmac, hashlib, json, re, time
def verify(raw: bytes, header: str, secret: str):
m = re.search(r"t=(\d+),v1=([0-9a-f]{64})", header or "")
if not m or abs(time.time() - int(m[1])) > 300: raise ValueError("stale")
mac = hmac.new(secret.encode(), f"{m[1]}.".encode() + raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(mac, m[2]): raise ValueError("bad signature")
return json.loads(raw)Answering and retries
Answer with any 2xx within 5 seconds; do the work afterwards. Anything else (or no answer) is retried after 30 s, 2 min, 10 min, 30 min, 1 h, 3 h, 6 h and 12 h, nine tries in all. Events can arrive twice and out of order: use id to skip ones you've handled, and the transaction's block to order them.
Webhook deliveries in usd.net/wallet/business lists the last 100 attempts with their status and time. Pausing the record stops deliveries.
Webhooks are a signal
The signature proves an event came from USD.NET. For money that matters, you can also read the transaction yourself, GET /tx/:hash signed by your server wallet, before shipping goods.