Proposed defaults. The retry schedule below follows industry conventions (Stripe’s 3-day, exponential-backoff retry; GitHub’s similar policy). Concrete intervals will be finalized with the BlooBank platform team before this scheme exits “Proposed” status.
Delivery guarantees
What counts as a successful delivery
Retry schedule
When a delivery fails transiently, BlooBank retries on an exponential schedule with jitter. The schedule below is the proposed default:
After attempt 9, the delivery is marked permanently failed and surfaced in the Dashboard. You can trigger a manual replay any time within the 30-day retention window.
Actual delays apply random jitter in the range
[delay × 0.5, delay × 1.5] to avoid thundering-herd recoveries.
deliveryAttempt in the event body and in the X-Bloobank-Delivery-Attempt header carries the 1-based attempt count — use it to recognize that you are receiving a redelivery (not necessarily a new event).
What your endpoint must guarantee
To play well with at-least-once delivery, your endpoint must be:
See Best practices for the implementation pattern.
Manual replay
Any delivery (whether successful or failed) can be replayed from the Dashboard:- Find the delivery by
messageIdor by the affected resource id. - Click Replay. BlooBank re-sends the original payload to your configured endpoint.
- The replay has the same
messageIdandeventas the original — your idempotent consumer treats it as a duplicate of the original event.
- Your endpoint was broken and you fixed it — replay missed events.
- A bug in your consumer skipped processing — replay to reprocess.
- You are testing changes to your endpoint — replay known-good events from history.
messageId. Replays are visually distinguished in the Dashboard log but otherwise indistinguishable from a normal retry.
Permanent failure → reconcile
If a delivery fails permanently and you do not catch it within 30 days, the event is gone from BlooBank’s delivery queue. But: the underlying state is still in the resource. You can always:status is authoritative — webhooks are a convenience layer for push notifications, not the only source of truth. A daily reconciliation pass that compares your local ledger against GET /paymentOrders?filter=...&order_by=createdAt%20desc will catch any missed events.
Operational best practices
Monitor your endpoint
Use a queue between ack and work
The 200 OK leaves your endpoint before the real work starts. If the work fails, you have already acknowledged — your retry logic is internal, not via BlooBank redelivery. This pattern keeps BlooBank’s retry contract clean and decouples your reliability from theirs.Test with the Dashboard
The Dashboard allows you to send test events to your endpoint without a real transaction occurring. Use these to validate signature verification, JSON parsing, and downstream handling in non-production environments.Tools
Next
Best practices
The idempotent consumer pattern.
Verifying signatures
Verify every delivery first.