# 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

```json title="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:

| 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.

```js title="Node (SDK)"
const event = await USDNet.verifyWebhook(rawBody, req.headers['usdnet-signature'], process.env.USDNET_WEBHOOK_SECRET);
```

```js title="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 title="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.
