Webhooks

Subscribe to settlement and payment events, and verify every delivery with your endpoint’s signing secret.

Webhooks

Register endpoints (scope webhooks) to receive events as they happen.

Events

Event	Fires when	data fields
payment_link.paid	a payment link is paid	id, status, amount, currency, payer_tx_hash, and paid_via: "x402" when an AI agent paid over x402
charge.settled	a Tap (point-of-sale) charge settles	id, status, amount, currency, tx_hash
fx.order.settled / .failed / .refunded	an FX order reaches that state	id, state, route, tx_hash
transfer.confirmed / .failed	a transfer reaches that state, including a broadcasting transfer that later confirms on-chain	id, state, kind, tx_hash
webhook.test	you call POST /webhooks/{id}/test	message

Subscribe to events by name when you register. An FX order that ends expired sends no webhook. Treat a webhook as a signal and read the resource (GET /fx/orders/{id}, GET /transfers/{id}, GET /payment-links/{id}) for its current state.

Delivery format

Each delivery is an HTTPS POST with a JSON body:

{
  "id": "evt_6f1c…",
  "type": "fx.order.settled",
  "created_at": "2026-10-22T09:14:03.120Z",
  "data": { "id": "…", "state": "settled", "route": "amm", "tx_hash": "0x…" }
}

and these headers:

Header	Value
BFX-Webhook-Signature	t=<unix seconds>,v1=<hex HMAC-SHA256>
BFX-Webhook-Id	The delivery id. Stays the same across retries of that delivery.
content-type	application/json

The body’s id (evt_…) identifies the event; BFX-Webhook-Id identifies the delivery. Use either to de-duplicate.

Verify every delivery

Your endpoint’s signing secret (whsec_…) is returned once, in the POST /webhooks response. Store it. To verify a delivery:

1. Read t and v1 from BFX-Webhook-Signature.
2. Compute HMAC-SHA256(secret, "<t>.<raw body>") as lower-case hex. Use the raw request body bytes exactly as received, before any JSON parsing.
3. Compare it to v1 in constant time. Reject on mismatch.
4. Reject the delivery if t is more than 5 minutes from your clock. This limits replay of a captured delivery.

import crypto from 'node:crypto';
import express from 'express';

const SECRET = process.env.BFX_WEBHOOK_SECRET; // whsec_…
const TOLERANCE_SECONDS = 300;

function verify(rawBody, header) {
  const parts = Object.fromEntries(String(header || '').split(',').map((p) => p.split('=')));
  const t = Number(parts.t);
  if (!Number.isFinite(t) || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) return false;
  const expected = crypto.createHmac('sha256', SECRET).update(`${parts.t}.${rawBody}`).digest('hex');
  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(parts.v1, 'hex');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

const app = express();
app.post('/bfx-webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const raw = req.body.toString('utf8');
  if (!verify(raw, req.get('BFX-Webhook-Signature'))) return res.status(400).end();
  const event = JSON.parse(raw);
  // de-duplicate on event.id, then handle event.type
  res.status(200).end();
});

Lost the secret? There is no way to read it again (a retried registration returns the body without secret). Delete the endpoint and register a new one.

Retries

A delivery succeeds when your endpoint answers any 2xx within 10 seconds. Anything else is retried on this schedule, measured from the previous attempt:

Attempt	When
1	as soon as the event occurs (normally within about 15 seconds)
2	1 minute later
3	5 minutes later
4	30 minutes later
5	2 hours later
6	6 hours later

That is 6 attempts over about 8 hours 36 minutes. If the sixth attempt fails, the delivery is dropped and the whole endpoint is disabled: it receives no further events. There is no re-enable call; delete the endpoint and register it again. Test deliveries follow the same rules.

Managing endpoints

POST   /webhooks           → register { url, events }  (returns the signing secret once; Idempotency-Key required)
GET    /webhooks           → list your endpoints and their status
POST   /webhooks/{id}/test → send a webhook.test delivery now
DELETE /webhooks/{id}      → remove an endpoint

• url must be HTTPS and resolve to a public address. Private, loopback and cloud-metadata addresses are refused with 400 invalid_url.
• events must list one or more of payment_link.paid, charge.settled, fx.order.settled, fx.order.failed, fx.order.refunded, transfer.confirmed, transfer.failed. webhook.test is not subscribable; it is sent only by the test call.
• Each account can have up to 10 active endpoints (409 endpoint_cap_reached).