Bloobank API Documentation

A webhook consumer that “works on the happy path” is easy. A consumer that survives retries, duplicates, out-of-order arrival, late replays, and partial failures is the actual goal. This page is the checklist of patterns that get you there. For the delivery contract, see Retry & delivery. For the document shape, see Webhook payload.

The non-negotiables

1. Verify the signature first

Before parsing, before logging, before anything. See Verifying signatures.

2. Deduplicate by (id, etag)

Two deliveries with the same order id and the same etag are the same state snapshot — process it once.

3. Guard ordering with ordVersion

Deliveries can arrive out of order. Ignore any snapshot whose ordVersion is lower than the highest you have processed for that id.

4. Persist, then acknowledge

Respond success only after durable persistence. An acknowledged delivery is never redelivered automatically.

Deduplicate by (id, etag)

Delivery is at-least-once: retries, and much later operator-driven replays, can hand you the same snapshot multiple times. The (id, etag) pair identifies one state snapshot of one order — use an atomic insert on it as the dedupe gate:

async function handleDelivery(order: PaymentOrder) {
  // Atomic insert on a unique (id, etag) index — the dedupe gate.
  try {
    await db.processedSnapshots.insertOne({
      orderId: order.id,
      etag: order.etag,
      at: new Date(),
    })
  } catch (e) {
    if (isDuplicateKey(e)) return   // same snapshot already handled — ack and move on
    throw e
  }
  await applyOrder(order)
}

If the same snapshot arrives twice concurrently, only one insert succeeds; the other path acknowledges without reprocessing.

Never deduplicate by signature. t and v1 in X-Webhook-Signature are fresh on every attempt — the signature of a retry never matches the original. Only payload fields (id, etag, ordVersion) are stable across attempts.

Guard ordering with ordVersion

Retries are asynchronous, so deliveries can arrive out of order. The classic case: an order settles as SUCCESS (say ordVersion: 3), your endpoint is briefly down, and the order is later REFUNDED (ordVersion: 4). The REFUNDED delivery succeeds immediately, then the retry of the older SUCCESS snapshot arrives afterwards. Without a guard, your ledger would roll the refund back to “paid”. ordVersion is a monotonic snapshot version — it increments on every state change. Track the highest version you have applied per order and refuse to go backwards:

async function applyOrder(order: PaymentOrder) {
  const local = await db.orders.findOne({ id: order.id })
  if (local && local.lastSeenVersion >= order.ordVersion) {
    return   // late delivery of an older snapshot — ignore
  }
  await db.orders.update(
    { id: order.id },
    {
      $set: {
        status: order.status,
        lastSeenVersion: order.ordVersion,
        etag: order.etag,
        updatedAt: order.updatedAt,
      },
    },
    { upsert: true },
  )
  await fireBusinessLogic(order)
}

With this guard, the late SUCCESS retry (version 3) is ignored because version 4 is already applied — your local view stays monotonically consistent no matter how scrambled the arrival order is.

Capture the raw body bytes

The signature is computed over the exact bytes on the wire. Any middleware that parses and re-serializes the JSON changes the bytes and breaks verification. Framework pitfalls:

Framework	Pitfall	Fix
Express	A global `express.json()` consumes and re-parses the body before your handler runs.	Mount `express.raw({ type: 'application/json' })` on the webhook routes, or capture the buffer with `express.json({ verify })`.
Flask / Django	Accessing the parsed form/JSON first can consume the stream.	Read `request.get_data()` / `request.body` before anything touches the request.
Spring	Binding to a POJO deserializes the JSON before you see it.	Bind the body as `byte[]` and deserialize after verification.
PHP	`$_POST` is useless for JSON bodies.	Read `file_get_contents('php://input')`.
ASP.NET Core	Model binding consumes the request stream.	Read `Request.Body` into a buffer yourself before any binding runs.
API gateways / WAFs	Body “sanitizers” that re-encode or pretty-print JSON change the bytes in flight.	Disable body transformations on the webhook path.

Verify defensively

Constant-time comparison, always. A plain == on the signature leaks timing information that lets an attacker forge signatures byte by byte. Use crypto.timingSafeEqual, hmac.compare_digest, hmac.Equal, MessageDigest.isEqual, hash_equals, or CryptographicOperations.FixedTimeEquals.
Enforce a freshness window. Reject deliveries where |now − t| exceeds 5 minutes. It bounds replay of captured requests and costs you nothing: every retry and every operator replay carries a fresh t and v1, so a rejected stale delivery is always redelivered with a valid recent signature.
Verify before parsing. Any unauthenticated request that reaches your business logic is an injection vector for fake payment confirmations. Verify, then parse, then act.
Never authenticate by source IP. The signature is the authentication contract; source IPs are not part of it and are not guaranteed stable. An IP allowlist may complement verification at your edge, but must never replace it.

Persist, then acknowledge

An acknowledged delivery is never redelivered automatically. If you respond success and then crash before persisting, that event is gone from your side. The order of operations inside the 10-second window is therefore fixed:

Verify the signature

Reject with 401 on failure — the retry arrives with a fresh signature.

Persist durably

Database write or durable queue. If persistence fails, respond 5xx — Bloobank retries.

Acknowledge

200, Content-Type: text/plain, body success. Only now is the delivery settled on both sides.

Do the real work asynchronously

Downstream calls, notifications, reconciliation — on a background worker, with your own internal retry logic. Bloobank’s retry contract ends at the acknowledgement.

Protect the secret

The webhook secret is symmetric — anyone holding it can forge deliveries that pass your verification. Handle it like a private key:

Rule	Why
Store it in a secret manager (GCP Secret Manager, AWS Secrets Manager, Azure Key Vault, HashiCorp Vault).	Never commit it, never bake it into images, never put it in plain environment files checked into a repo.
Never log the secret.	Log only the verification result (pass/fail), never the inputs.
Avoid logging `(signature, body)` pairs.	Shared log aggregators become an offline forgery-analysis corpus, and the body carries payment data.
Alert on verification-failure bursts.	Sustained invalid signatures mean configuration drift (e.g. a secret mismatch after rotation) or someone probing your endpoint. Both deserve a page.

Rotate the secret in coordination with Bloobank

There is a single active secret per merchant — it signs deliveries to both your cash-in and cash-out endpoints. Rotation is a coordinated cutover scheduled with Bloobank, not a self-service operation, and there is no overlap window where two secrets are valid. Plan the cutover accordingly:

Contact Bloobank to schedule the rotation.
Stage the new secret in your secret manager ahead of the agreed cutover time.
At cutover, switch your verifier to the new secret. Deliveries signed with the old secret that are retried after the cutover are re-signed with the new secret — the freshness window and retry contract make the switch safe.
Watch your verification-failure metric during the window: a sustained burst means one side switched and the other did not.

Observability checklist

Metric	Alert when
Ack latency (p50, p99)	p99 approaches the 10-second deadline.
Non-`success` response rate	Above zero, sustained — every one triggers a retry.
Signature verification failures	Above zero, sustained for minutes — configuration drift or probing.
Duplicate `(id, etag)` rate	Spikes — usually correlates with your endpoint acknowledging incorrectly or slowly.
Out-of-order (`ordVersion`) discards	Informational — confirms the guard is doing its job.
Background worker queue depth	Grows monotonically — you are not keeping up.

Verifying signatures

Worked example, test vector, six reference verifiers.

Retry & delivery

Backoff schedule and operator-driven replay.

Webhook payload

The canonical PaymentOrder document.

Introduction

Concepts

Authentication

Errors

Wallets

Payments

Webhooks

Best practices

The non-negotiables

1. Verify the signature first

2. Deduplicate by (id, etag)

3. Guard ordering with ordVersion

4. Persist, then acknowledge

Deduplicate by (id, etag)

Guard ordering with ordVersion

Capture the raw body bytes

Verify defensively

Persist, then acknowledge

Protect the secret

Rotate the secret in coordination with Bloobank

Observability checklist

Next

Verifying signatures

Retry & delivery

Webhook payload

​The non-negotiables

1. Verify the signature first

2. Deduplicate by (id, etag)

3. Guard ordering with ordVersion

4. Persist, then acknowledge

​Deduplicate by (id, etag)

​Guard ordering with ordVersion

​Capture the raw body bytes

​Verify defensively

​Persist, then acknowledge

​Protect the secret

​Rotate the secret in coordination with Bloobank

​Observability checklist

​Next

Verifying signatures

Retry & delivery

Webhook payload

The non-negotiables

Deduplicate by (id, etag)

Guard ordering with ordVersion

Capture the raw body bytes

Verify defensively

Persist, then acknowledge

Protect the secret

Rotate the secret in coordination with Bloobank

Observability checklist

Next