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.

HeaderMeaning
X-Send21-EventThe event type
X-Send21-DeliveryUnique delivery id; retries reuse it, so use it to ignore duplicates
X-Send21-SignatureOriginal 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-TimestampWhen the delivery was sent, in Unix seconds
X-Send21-Signature-V2t=<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

EventWhen
draft.createdA draft was created: by you, an API key, a recurring template, or a payer picking a currency on a pay link
draft.seenA payment was seen but is not confirmed yet. Also sent with acceptedByOwner: true when you accept a payment with a different amount
draft.confirmedThe payment reached its required confirmations. For Lightning: the provider confirmed it with a valid preimage
draft.amount_mismatchA transfer within 10% of the billed amount arrived (reviewState: pending). It does not pay the draft until you accept it. Sent once
draft.mismatch_rejectedYou 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_reminderStill undecided 2 hours before the draft expires. Sent once
draft.mismatch_unresolvedThe draft expired (or was cancelled) while the transfer was undecided. Money arrived; nobody decided. You can still accept it
draft.expiredThe 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_acceptedA 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.expiredA 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.cancelledThe draft was cancelled
testSent 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 orderId and 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.