Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.bloobank.com/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks let Bloobank notify your system in real time when something relevant happens — a confirmed transaction, a failed payment, an updated balance. Instead of periodically polling lookup endpoints, your server receives an HTTP POST call at the moment of the event.

​
How it works

1

Configure the endpoint

In the Bloobank Dashboard, go to Tools → Webhooks and register the public URL of your server that will receive events.
2

Bloobank sends events

Whenever an event happens, Bloobank sends a POST request to the configured endpoint with a standardized JSON envelope.
3

Your server responds 2xx

Your server must respond with a 2xx status in under 10 seconds to confirm receipt.
4

On failure, automatic retry

If your endpoint does not respond with 2xx, Bloobank attempts to redeliver the event following the retry policy described below.

​
Event envelope

All webhooks follow the same base format: 
{
  "event": "payment.confirmed",
  "messageId": "msg_8H2kPqR9zT4xVm",
  "method": "POST",
  "pathname": "/topic/api-payments/payment/v1",
  "body": {
    "id": "pixin_123456789",
    "amount": 15000,
    "currency": "BRL",
    "status": "confirmed",
    "endToEndId": "E1234567820260506110000000012345",
    "createdAt": "2026-05-06T10:30:00Z",
    "confirmedAt": "2026-05-06T10:30:05Z"
  },
  "query": {}
}
FieldTypeDescription
eventstringEvent name (e.g. payment.confirmed). See the catalog at Payment events.
messageIdstringUnique delivery identifier. Use it for idempotency on your side.
methodstringHTTP method used by Bloobank. Always POST in the current version.
pathnamestringInternal event routing (e.g. /topic/api-payments/payment/v1).
bodyobjectFull resource at the event’s state. Same shape returned by the corresponding GET.
queryobjectOptional query parameters. Usually {}.

​
Idempotency

The same delivery can arrive more than once in retry scenarios. Your server must be idempotent.
1

Persist the messageId

On receipt, record the messageId in a processed-events table.
2

Check before processing

Before applying the effect of the event (update balance, mark order as paid), check whether the messageId was already processed.
3

Respond 2xx even on duplicates

If the event was already processed, respond 200 OK without reprocessing. This stops Bloobank from continuing to redeliver.

​
Retry policy

TODO (needs to be filled manually): The exact retry policy — number of attempts, interval between attempts, backoff (linear, exponential), maximum time until give-up, and handling of 4xx vs 5xx errors — must be confirmed with the Bloobank platform team before publishing.
General recommendation until the final definition:
  • Treat the webhook as eventually consistent — it may be delayed by seconds to minutes.
  • On a 5xx error from your server, Bloobank will attempt redelivery.
  • On a 4xx error, the delivery may be marked as permanently failed.
  • Undelivered events can be manually reprocessed via the Dashboard.

​
Signature and verification

TODO (needs to be filled manually): The webhook signature scheme (signature header, algorithm, shared secret, signed payload format) must be defined and documented by the platform team. Without this, the integrator cannot verify the authenticity of received events.
Best practices to apply once the signature is defined:
  • Verify the signature before processing the event.
  • Reject events with very old timestamps (replay protection).
  • Use HTTPS on your public endpoint.
  • Restrict by IP or private network where possible.

​
Best practices

Respond 2xx immediately after validating the event. Push the actual work (update database, send email) onto an async queue. Bloobank’s timeout is short.
Keep a persistent log of every messageId received, with timestamp and processing status. Useful for reconciliation and support.
The body reflects the state at the moment of emission. To guarantee consistency, perform a GET on the corresponding endpoint after receiving the event.
Use distinct endpoints for sandbox and production. Never point the sandbox at your production server.

​
Next steps

Payment events

See the catalog of events fired by Bloobank throughout the lifecycle of a payment order.