Skip to main content
Webhooks let Bloobank push payment outcomes to your service instead of you polling for them. When a PaymentOrder reaches a settled status, Bloobank sends a signed HTTP POST with the canonical order document to one of your registered endpoints. Your endpoint has exactly two obligations per delivery:
  1. Verify the signature before trusting the payload — see Verifying signatures.
  2. Acknowledge with the literal response body success — this string, together with a 2xx status, is the only thing that records the delivery as successful. Anything else, including ok, counts as a failed delivery and triggers redelivery.

​
Your two endpoints

You register two HTTPS URLs with Bloobank during onboarding: Both endpoints share the same per-merchant webhook secret; only the URL differs. The URLs are called exactly as registered — no path suffixes, no query parameters are appended.
Endpoint registration happens at onboarding, not through a self-service console. To change a URL or rotate the secret, contact Bloobank — secret rotation is a coordinated cutover (there is a single active secret per merchant, with no overlap window). See Best practices.
HTTPS is mandatory. Bloobank refuses to register a non-HTTPS webhook URL. Your endpoint must present a publicly-trusted TLS certificate.

​
When webhooks fire

A webhook is delivered when a PaymentOrder reaches a settled status. Intermediate states never generate a webhook. There are no event names — the body is the flat canonical PaymentOrder document itself, no envelope. The order’s status field tells you what happened, and direction tells you which endpoint received it. See Webhook payload for the full document shape and Payment lifecycle for state semantics.

​
What a delivery looks like

Every webhook is an HTTP POST to one of your registered URLs:
Other transport headers may be present; none of them participate in the signature.

​
The response deadline

Bloobank waits 10 seconds (current default) for your complete response — connection, processing, and body included. An attempt that times out counts as a failed delivery and is retried per the retry policy.
Keep the synchronous path short: verify, persist, acknowledge. Push anything slower — downstream calls, notifications, reconciliation — onto a background queue after acknowledging.

​
Acknowledging a delivery — the success contract

A delivery is recorded as successful only when your endpoint responds with an HTTP 2xx status AND a response body that is exactly the string success. A 2xx status alone is not enough. This is deliberate: a 200 OK can come from a load balancer, a CDN, or a catch-all route without your handler ever running. The literal body proves your application code executed and accepted the event.

​
The canonical acknowledgement

Matching is trimmed and case-insensitive (Success, SUCCESS, or a trailing newline are all accepted), but always emit the canonical form: status 200, Content-Type: text/plain, body success in lowercase, no quotes, no JSON.

​
What counts — and what does not

Returning ok is not accepted. Several PSP ecosystems acknowledge webhooks with the body ok. Bloobank does not. Returning ok — with any status — is treated exactly like an error: the delivery is retried and eventually parked for manual replay. The only accepted token is success.

​
Acknowledge only after durable handling

An acknowledged delivery is never redelivered automatically. If you respond success and then crash before persisting the event, that event is gone from your side. Persist first (database write, durable queue), acknowledge second. If persistence fails, respond with a 5xx — Bloobank will retry.

​
Handling a delivery, step by step

1

Capture the raw body bytes

Before any framework body-parser or JSON deserialization touches them — the signature is computed over the exact bytes on the wire.
2

Verify the signature

Parse X-Webhook-Signature, recompute the HMAC-SHA512, compare in constant time, and check freshness. Reject with a non-2xx (e.g., 401) on any failure. See Verifying signatures.
3

Parse, deduplicate, and guard ordering

Parse the JSON only after verification. Deduplicate by (id, etag) and ignore deliveries whose ordVersion is lower than one you already processed for that order. See Best practices.
4

Persist durably

Write the event to your database or a durable queue before acknowledging.
5

Acknowledge with success

Respond 200, Content-Type: text/plain, body success — within the 10-second deadline.

​
Next

Verifying signatures

The HMAC-SHA512 scheme, worked example, test vector, and verifiers in six languages.

Retry & delivery

At-least-once delivery, the backoff schedule, and operator-driven replay.

Webhook payload

The canonical PaymentOrder document and its instrument variants.

Best practices

Idempotency, ordering, raw-body capture, and secret handling.