Skip to main content
Webhook delivery is at-least-once. A delivery that is not correctly acknowledged is retried with exponential backoff, and — if all attempts fail — parked for operator-driven replay. Design your consumer for duplicates and out-of-order arrival from day one.

​
What counts as a failed delivery

A delivery attempt fails when any of the following happens: The only successful outcome is a 2xx status with the literal body success (trimmed, case-insensitive). See the full acknowledgement contract.
There is no “permanent failure” status code. Unlike schemes where a 4xx stops redelivery, Bloobank retries every failed attempt on the same schedule regardless of status code. If your endpoint rejects a delivery (for example, a signature failure), the retry arrives later with a fresh, valid signature — a transient clock or deploy issue self-heals.

​
Retry schedule

Failed deliveries are retried with exponential backoff and jitter: Up to 6 attempts in total (initial + 5 retries), spanning roughly 1.5 to 3 hours.
These are current Bloobank-side defaults, indicative rather than contractual. The schedule may be tuned over time. Design for at-least-once delivery under any schedule — never encode the attempt count or timing into your business logic.

​
After the last attempt: parked for replay

When all automatic attempts are exhausted, the event is parked for operator-driven replay. It is not lost — a Bloobank operator can redeliver it manually, potentially hours or days later, typically after you have fixed your receiver and coordinated a replay.
A very late duplicate is normal, not a bug. Your deduplication by (id, etag) and the ordVersion ordering guard handle replayed events exactly like any other redelivery — see Best practices. Do not enforce your signature freshness window as an argument against replays: replayed deliveries are re-signed with a fresh t and v1, so they always pass verification.
If your endpoint was down beyond the automatic retry span, contact Bloobank to schedule a replay of the parked events.

​
What stays stable across attempts — and what does not

Every attempt of the same event carries: Two consequences:
  • Deduplicate by (id, etag), never by signature. t and v1 change on every attempt; only payload fields are stable.
  • Enforcing a freshness window is always safe. Rejecting a stale delivery never strands an order — the retry arrives with a valid recent signature.

​
What your endpoint must guarantee

​
Monitoring and alerting

Instrument your receiver — retries make delivery robust, but only monitoring tells you why they are happening:
Alert on sustained signature verification failures. A burst of invalid signatures means either configuration drift (for example, a secret mismatch after a coordinated rotation) or someone probing your endpoint. Both deserve a page, not a log line.

​
Next

Best practices

Deduplication, ordering, and the idempotent consumer pattern.

Verifying signatures

Verify every attempt before processing.