Users and money

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

typeWhen
charge.succeeded / charge.failedA charge from your server wallet was sealed or refused by the block
payout.succeeded / payout.failedA payout from your server wallet
payment.receivedA user (or anyone) transferred USD₮ to one of your server wallets, e.g. USDNet.pay
transfer.sentA transfer from one of your server wallets (a sweep, a bridge withdrawal)
mandate.createdA user gave one of your server wallets a mandate (or replaced one)
mandate.revokedA user revoked it
user.creditedUSD₮ arrived in the account of a user whose mandate lets you read it: a deposit, a transfer, a payout from someone else
pingSend test event in usd.net/wallet/business

Payload

POST https://api.example.com/usdnet/webhook
{
  "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:

HeaderValue
usdnet-signaturet=<unix seconds>,v1=<hex HMAC-SHA256>
usdnet-eventThe event type
usdnet-deliveryThe event id, the same on every retry
user-agentUSD.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.

Node (SDK)
const event = await USDNet.verifyWebhook(rawBody, req.headers['usdnet-signature'], process.env.USDNET_WEBHOOK_SECRET);
Node (no SDK)
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);
}
Python
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.