Webhooks
Webhooks (also known as web callbacks) let you receive real-time notifications whenever an event occurs in an integrated system. Data is delivered via HTTP POST requests to your configured endpoint — no polling required.
Each webhook request contains details about the event and the resource involved.
Setup
Authentication
An authentication method must be configured on your destination URL before webhooks can be
delivered. Both Basic and Bearer are supported — you pick one through
authenticationType when registering:
| Method | authenticationType | What you configure | Header LB Pay sends |
|---|---|---|---|
| Basic | 0 | webhookUserName + webhookPassword | Authorization: Basic base64(user:password) |
| Bearer | 1 | authentication.token | Authorization: Bearer <token> |
Reject any request that does not carry the expected header — an unauthenticated webhook endpoint is an open door to fabricated payment confirmations.
Configuration
Configure your webhooks via the API Reference: https://developers.lbpay.com.br/api/#tag/Webhook
Response requirements
Your endpoint must respond 2xx within 5 seconds. Slow responses are treated as failed
deliveries and trigger unnecessary retries from the platform.
receive event → persist to queue or database → return 200
↓
process asynchronously
Your response code decides what happens next:
| Your response | LB Pay behaviour |
|---|---|
2xx | Accepted — no retry |
5xx | Retried, up to 3 attempts with backoff |
4xx | Not retried — logged, and may go to a dead-letter queue |
Business logic — crediting a wallet, notifying a player, calling another service — must run
outside the synchronous request. Persist the event, return 200, and let a worker do
the work.
A handler that credits balance inline will eventually time out mid-credit, and the platform will redeliver the same event to a system that has already moved money.
Registration probes your endpoint
LB Pay calls your URL when you register it. The configuration is only accepted if the probe
succeeds, and the response comes back with validated: true.
Registering a URL that is not deployed yet fails immediately with webhook_unreachable,
webhook_timeout or webhook_http_error. The URL must also be HTTPS — plain HTTP is
rejected with invalid_protocol.
Deploy the endpoint first, even if it does nothing but return 200, then register it.
Not every event is an ending
Some events report progress, not an outcome. pixChargeRejected is the one that catches
integrations out: it carries "status": "pending", meaning a payment attempt failed while
the charge itself stays open and payable.
Branch on the status field, not on the event name alone. Only act when the status is
terminal — see Deposits.
Reliability
Webhooks are the primary notification channel, but delivery is not guaranteed. Your integration needs both:
| Mechanism | Role |
|---|---|
| Webhooks | Primary — low latency notification |
| Contingency polling | Mandatory fallback for lost events |
Deliveries also repeat, and can arrive out of order. Never derive state from arrival order: ignore anything that would move a transaction backwards from a terminal status, and deduplicate before crediting — see Credit exactly once.
Next
- Events — the catalogue and payload of every event
- Idempotency — the same problem on the sending side