Webhooks
send21 calls your server when a draft changes. Register an endpoint with POST /api/v1/webhooks (scope webhooks:manage) and the events you want. The response contains the signing secret once. Send a test event any time with POST /api/v1/webhooks/{id}/test.
Delivery
Each delivery is a POST with Content-Type: application/json and the body { "event": "<type>", "data": { ... } }. Any 2xx response counts as delivered. Anything else, or no answer within 15 seconds, is retried after 1, 2, 4, 8 minutes and so on, up to 8 attempts. Deliveries can arrive out of order.
| Header | Meaning |
|---|---|
X-Send21-Event | The event type |
X-Send21-Delivery | Unique delivery id; retries reuse it, so use it to ignore duplicates |
X-Send21-Signature | Original signature, only for endpoints registered before 16 November 2026: sha256= plus the lowercase hex HMAC-SHA256 of the raw body, keyed with your secret. It has no timestamp; endpoints registered since get V2 only |
X-Send21-Timestamp | When the delivery was sent, in Unix seconds |
X-Send21-Signature-V2 | t=<timestamp>,v1=<hex HMAC-SHA256 of "<timestamp>.<delivery id>.<raw body>">. Recommended: it also signs the time and the delivery id, so a copied delivery cannot be replayed. Refuse deliveries more than 300 seconds (5 minutes) old |
Verify the signature
Check X-Send21-Signature-V2: compute the HMAC over <timestamp>.<delivery id>.<raw body>, using the raw request bytes before parsing JSON, compare in constant time and refuse deliveries more than 300 seconds (5 minutes) old. Answer 401 when the header is missing or wrong. An older integration that checks X-Send21-Signature (HMAC of the raw body only) keeps working, but a copied delivery passes that check again. Before you ship goods, check that the amount, currency and orderId are the ones you expect.
// X-Send21-Signature-V2: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<delivery id>.<raw body>">
const sig = String(req.headers['x-send21-signature-v2'] ?? '');
const t = /(?:^|,)t=(\d+)/.exec(sig)?.[1];
const v1 = /(?:^|,)v1=([0-9a-f]{64})/.exec(sig)?.[1];
const deliveryId = String(req.headers['x-send21-delivery'] ?? '');
const fresh = t !== undefined && Math.abs(Date.now() / 1000 - Number(t)) <= 300;
const expected = crypto.createHmac('sha256', secret)
.update(t + '.' + deliveryId + '.').update(rawBody).digest('hex');
const ok = fresh && v1 !== undefined &&
crypto.timingSafeEqual(Buffer.from(v1, 'hex'), Buffer.from(expected, 'hex'));
if (!ok) return res.status(401).end();The same check in Python
import hmac, hashlib, re, time
sig = request.headers.get("X-Send21-Signature-V2", "")
t = re.search(r"(?:^|,)t=(\d+)", sig)
v1 = re.search(r"(?:^|,)v1=([0-9a-f]{64})", sig)
delivery_id = request.headers.get("X-Send21-Delivery", "")
valid = False
if t and v1 and abs(time.time() - int(t.group(1))) <= 300:
signed = t.group(1).encode() + b"." + delivery_id.encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
valid = hmac.compare_digest(expected, v1.group(1))Events
| Event | When |
|---|---|
draft.created | A draft was created: by you, an API key, a recurring template, or a payer picking a currency on a pay link |
draft.seen | A payment was seen but is not confirmed yet. Also sent with acceptedByOwner: true when you accept a payment with a different amount |
draft.confirmed | The payment reached its required confirmations. For Lightning: the provider confirmed it with a valid preimage |
draft.amount_mismatch | A transfer within 10% of the billed amount arrived (reviewState: pending). It does not pay the draft until you accept it. Sent once |
draft.mismatch_rejected | You declined it with rejectReason. Carries both amounts and refund: "manual": the money is in your wallet and any refund is up to you |
draft.mismatch_reminder | Still undecided 2 hours before the draft expires. Sent once |
draft.mismatch_unresolved | The draft expired (or was cancelled) while the transfer was undecided. Money arrived; nobody decided. You can still accept it |
draft.expired | The draft expired unpaid. If a transfer with a different amount was undecided, receivedAmountSats and reviewState: unresolved are set. For pay-link payments it also says opened and quoteRequested |
draft.mismatch_accepted | A payment with a different amount was accepted: by you, with acceptReason, or by the draft's shortfallPolicy (acceptReason: "auto: shortfallPolicy"). Carries the expected and received amounts |
payment_request.expired | A pay link expired unpaid. opened: the payer loaded the pay page (link previews and bots ignored). quoteRequested: they picked a currency. No IP or payer data |
draft.cancelled | The draft was cancelled |
test | Sent by the test endpoint |
Payload
draft.seen, draft.confirmed, draft.amount_mismatch and draft.expired share this shape. Amounts ending in Sats are base units of the sent asset: 8 decimals for BTC, 6 for USDC, USDT and EURC, 9 for SOL and ETH (ETH in gwei). txId is the transaction id, or the payment hash for Lightning. receivedAmountSats and receivedAmount appear when the amount differs from the billed amount, including on the draft.confirmed of an accepted short or over payment. paymentRequestId and orderId are set for pay-link payments. quoteId names the quote (rate lock) a fiat-priced payment was matched against. confirmedAt is set once the draft is confirmed and never changes. Timestamps are always UTC with three fraction digits and Z, the same as in the REST API.
{
"event": "draft.confirmed",
"data": {
"draftId": "3f6c2a9e-5d1b-4c8e-9a7f-2b4d6e8f0a1c",
"quoteId": "9b2e7c41-6a3d-4f8e-b1c5-0d9a8e7f6c2b",
"status": "Confirmed",
"txId": "5KqZ9bQ...",
"confirmations": 1,
"sentCurrency": "USDC",
"network": "Solana",
"amountSats": 50000000,
"sentAmount": "50.000000",
"fiatCurrency": "EUR",
"fiatAmount": 46,
"conversionRate": 0.92,
"rateSource": "coinbase",
"platformFee": { "accrued": true, "waived": false, "percent": 0.39, "feeUsd": 0.2,
"feeBaseUnits": 195000, "feeAmount": "0.195000", "currency": "USDC" },
"paymentRequestId": "8d1e4b7a-0c2f-4e6d-b3a9-7f5c1e2d4a6b",
"orderId": "ORDER-1042",
"confirmedAt": "2026-10-06T08:22:21.000Z",
"occurredAt": "2026-10-06T08:22:22.000Z"
}
}Endpoint rules
- Endpoints must use HTTPS and resolve to a public address; private and internal addresses are refused.
- Store the secret in a secret manager. It is shown only once.
- Reconcile with
orderIdand the exact amount, not with the time of arrival.
Related
Start building
Create a free account to get an API key, or try the whole flow first on test networks.
This page is also available as Markdown: /docs/webhooks.md. Questions: integration@send21.io.