Architecture
Webhook events
FurlPay receives provider webhooks and can deliver merchant payment events to a configured HTTPS endpoint. The signature header and freshness rules depend on which direction and provider you are integrating.
Events FurlPay sends to merchants
A merchant can register an HTTPS endpoint through the authenticated /api/merchant/webhook API. The current outbox event types are payment.succeeded and invoice.paid.
| Method | Path | Description |
|---|---|---|
| GET | /api/merchant/webhook | Read the signed-in merchant's endpoint; secret is never returned |
| PUT | /api/merchant/webhook | Set an HTTPS endpoint and rotate its secret; plaintext secret is returned once |
| DELETE | /api/merchant/webhook | Remove the signed-in merchant's endpoint |
Delivery is at-least-once. Deduplicate on X-FurlPay-Event-Id; retries use the same event ID. The endpoint must return a 2xx response. Delivery retries are bounded, and the payment ledger remains the source of truth.
X-FurlPay-Event-Ididentifies the outbox event.X-FurlPay-Attemptis the delivery attempt number.X-FurlPay-Signatureusest=<unix>,v1=<hex>.
The signature is HMAC-SHA256 over timestamp + "." + rawBody using the endpoint secret. Reject timestamps outside the five-minute tolerance, compare signatures in constant time, and parse the JSON only after verification. The Node SDK verification helper accepts the signature value; pass it the value of the X-FurlPay-Signature header.
Merchant webhook delivery can be unavailable
FURLPAY_PARTNER_WEBHOOK_KEY. If endpoint configuration returns 503, do not assume events are being delivered.Provider webhooks FurlPay receives
| Method | Path | Description |
|---|---|---|
| POST | /api/webhooks/stripe | Stripe events; Stripe SDK signature verification over the raw body |
| POST | /api/webhooks/sumsub | Sumsub verification outcomes; HMAC digest headers |
| POST | /api/webhooks/persona | Persona inquiry outcomes; timestamped signature validation and user-binding check |
| POST | /api/webhooks/deposit-detect | Configured chain-provider deposit notifications; provider HMAC validation |
| POST | /api/webhooks/complyadvantage | Configured screening-provider events |
| POST | /api/webhooks/card-auth | Card-auth events; signed, timestamped payload verification |
Configure each provider's credentials and endpoint secret separately. Handlers verify provider-specific headers before trusting payloads, and some may fail closed with 503 when production configuration is absent. Do not reuse a secret or verification snippet across providers without confirming their exact scheme.
Local development
The @furlpay/cli package includes webhook-forwarding commands for development. Use test events and a test endpoint secret locally. A forwarded or simulated event is not evidence of a production payment.
Never credit a balance from an unverified event