Skip to main content
Webhooks let BlooBank push events to your service in real time. Instead of polling endpoints to discover state changes, your server receives a signed HTTP POST at the moment of every lifecycle transition — payment order created, approved, processing, settled, failed, expired.
The webhook signing and retry policies below are proposed defaults aligned with industry conventions (Stripe, GitHub). The concrete header names and retry intervals will be finalized in coordination with the BlooBank platform team before exiting “Proposed” status.

​
How it works

1

Register your endpoint

Configure your webhook endpoint URL in the BlooBank Dashboard. Each environment (sandbox / production) holds its own configuration.
2

BlooBank delivers events

On every lifecycle transition, BlooBank sends a POST request with a JSON body and signature headers.
3

Your endpoint verifies the signature

See Verifying signatures. Reject any delivery that fails verification.
4

Your endpoint responds 2xx fast

Respond 200 OK within 10 seconds. Do the real work (database writes, downstream calls, email sends) on a background queue.
5

On non-2xx or timeout, BlooBank retries

Following the retry policy. Your endpoint must be idempotent — see Best practices.

​
The envelope

Every webhook is a JSON object with the same envelope shape:

​
Delivery headers

BlooBank sends these headers on every webhook:

​
Your response

Respond fast. The 10-second timeout is firm. Push real work onto a background queue and acknowledge the delivery immediately.

​
Configuring an endpoint

Each environment supports one or more webhook endpoint URLs, scoped per event class (e.g., one endpoint for payment-order events, another for future event families). Requirements:
  • HTTPS only (HTTP rejected).
  • Public address (no localhost or RFC 1918 addresses).
  • Valid TLS certificate from a publicly trusted CA.
Best practice: configure distinct endpoints per environment. Never point a sandbox configuration at your production server.

​
Event classes

Today, BlooBank emits one class of webhook events: See Payment events for full payloads and per-event semantics.

​
Order and duplication

Webhooks are at-least-once with no order guarantees:
  • A single state transition may be delivered more than once. Your consumer must deduplicate by messageId.
  • Two transitions on the same order may arrive out of order (e.g., success before processing). Treat the data payload as the source of truth — the state inside is always the order’s actual current state at the moment of delivery.
See Best practices for the idempotent consumer pattern.

​
Delivery latency

Typical end-to-end latency from state change to webhook arrival: Webhooks are eventually consistent — designed for reconciliation, not for replacing synchronous responses. For the freshest state, you can always GET the resource directly; the webhook is the push notification that something interesting happened.

​
When delivery fails permanently

If retries exhaust without success, the delivery is marked failed and surfaced in the Dashboard. You can:
  1. Inspect the delivery payload and your endpoint’s response.
  2. Trigger a manual replay (after fixing the receiver).
  3. Reconcile by polling the resource — webhooks are a convenience layer, not a strict requirement.

​
What webhooks do not replace

  • The signed-request authentication for outbound API calls — separate concern.
  • Idempotency on creates — supply idempotencyKey regardless of whether you receive a webhook back.
  • Periodic reconciliation — webhook delivery is at-least-once; a missed message can occur in extreme failures. Compare local ledger against GET /paymentOrders daily.

​
Next

Verifying signatures

HMAC-SHA256 scheme — verify every delivery.

Retry & delivery

The retry policy in detail.

Payment events

Event catalog and payloads.

Best practices

Idempotency, ordering, deduplication.