Overview
How BlendFi tells you something happened. Mental model, available events, webhook vs polling decision, production pattern.
Webhooks are how BlendFi tells you something happened: a Pix arrived, a KYC was approved, a USDT deposit confirmed on-chain. They are cheaper, faster, and more reliable than polling.
When BlendFi POSTs to you
Every state change on the partner-visible surface fires exactly one webhook event. Event types group into:
- Conversion lifecycle (7 events):
conversion.created,conversion.standby,conversion.completed,conversion.failed,conversion.expired,conversion.canceled,conversion.abandoned. - Transaction (settlement leg) (3 events):
transaction.sending_pix,transaction.completed,transaction.failed. Optional, finer-grained settlement visibility. - End-customer KYC (4 events):
user.kyc_pending,user.kyc_approved,user.kyc_rejected,user.kyc_expired.
The full list with payload examples lives in the event catalog.
Webhooks vs polling
Polling is fine for occasional reconciliation (GET /v1/conversions/:id is rate-limit safe within reasonable bounds). Webhooks are the right choice when:
- You need to react in seconds, not minutes (e.g. show the end customer "payment received" the moment Pix settles).
- You're handling more than a handful of conversions per day (polling cost grows linearly).
- You have an HTTPS endpoint under your control.
You don't have to choose. Most production integrations subscribe to webhooks for fast reaction and use polling only as a reconciliation safety net (a daily cron that fetches "any conversion still in progress" and validates against local state).
The production bar
Checklist for a production-ready partner integration:
- HTTPS endpoint registered via
POST /v1/webhook_endpoints. See Endpoint management. - Signature verification on every delivery: HMAC-SHA256 over
{t}.{raw_body}, constant-time comparison, 300-second replay window. See Signature verification. - Idempotent processing: dedupe on
X-Blendfi-Event-Id. - Fast ack: return 2xx in under 500 ms; do the real work asynchronously.
- Concrete retry plan: accept retries gracefully; a 5xx from your endpoint triggers a new attempt in about 30 seconds. See Retries and replay.
- Subscription scope: subscribe only to the events you process. New events are added additively; subscribing to all does not break when new ones arrive, but minimizes noise.
- Secret rotation runbook: rotate via
POST /v1/webhook_endpoints/{id}/rotate_secretahead of any compromise scare. See Endpoint management. - Delivery history access:
GET /v1/webhook_endpoints/{id}/deliveries. Useful for diagnosis: "did BlendFi try to reach us at this time?" - Manual redelivery:
POST /v1/webhook_deliveries/{id}/redeliverto replay a specific event after a fix. - Local test loop: trigger
test_helpersendpoints in sandbox to exercise the lifecycle without waiting for real payments. See Sandbox testing.
Don't skip signature verification
An unauthenticated webhook receiver exposes a remote-code-execution surface to the public internet. Verify signatures on every request, fail closed, and log signature failures to detect attack attempts early.
Pages in this section
Endpoint management
Create, list, update, delete endpoints. Rotate secret without downtime.
Signature verification
HMAC-SHA256, headers, working code in curl, Node, and Python.
Event catalog
Each type with payload examples, when each fires, what to do.
Retries and replay
Schedule, status semantics, dead-letter, manual redelivery.
Sandbox testing
Trigger deliveries via test_helpers, debug signature mismatches.