These webhooks are essential for keeping your system in sync, especially in asynchronous flows where a response alone isn’t enough (like transaction confirmation, cash-in, or reversals).
Webhook setup
To receive Pix webhooks, your system must:
- Expose a public HTTPS endpoint.
- Respond with status
200 OK within 5 seconds.
- Validate and process the event payload.
- Optionally verify the webhook signature (recommended)
ImportantIf your endpoint doesn’t respond with 200, we’ll retry the webhook automatically using exponential backoff with a TTL of 24 hours.
Webhook types
Here are the main webhooks you might receive:
pix.transaction.status
Sent whenever a Pix transaction’s status changes, typically from pending to confirmed or failed.
{
"type": "pix.transaction.status",
"transactionId": "txn_12345",
"status": "confirmed",
"amount": 200.00,
"updatedAt": "2025-07-11T13:00:00Z"
}
| Field | Description |
|---|
type | Event type (pix.transaction.status) |
transactionId | Your transaction identifier. |
status | pending, confirmed, failed, or reversed |
amount | Transaction amount. |
updatedAt | Time of final status confirmation. |
TipUse this webhook to update your UI or internal ledgers. Never assume a transaction is complete based solely on the API response.
pix.cashin.received
Triggered when your user receives a Pix from another institution (cash-in).
{
"type": "pix.cashin.received",
"recipientAccountId": "acc_5678",
"amount": 950.00,
"receivedAt": "2025-07-11T11:45:00Z",
"senderName": "John Smith",
"senderKey": "[email protected]"
}
- The Pix plugin receives a webhook from the PSTI.
- It verifies the recipient account.
- It credits the amount to the account.
- Then it notifies your system with this event.
pix.message.received (MED)
In some cases, the PSTI may send direct messages to the Authorizer. These include updates not tied to a transaction.
{
"type": "pix.message.received",
"content": {
"messageType": "notice",
"reference": "ref_234",
"details": "PSTI maintenance scheduled"
},
"receivedAt": "2025-07-11T10:00:00Z"
}
- Forwarding alerts to your team.
- Logging system-level events.
- Triggering operational workflows.
pix.reversal.processed
Triggered when a Pix reversal is successfully completed, either by your system or due to a webhook received from the PSTI.
{
"type": "pix.reversal.processed",
"transactionId": "txn_12345",
"refundedAmount": 200.00,
"processedAt": "2025-07-11T13:30:00Z"
}
- Update internal balances.
- Notify your user.
- Track full reversal history.
Retry behavior
If your endpoint is down or returns an error, we’ll retry the webhook using exponential backoff, with delays increasing up to a 24-hour TTL.
| Attempt | Delay before retry |
|---|
| 1st | Immediate |
| 2nd | 10 seconds |
| 3rd | 1 minute |
| 4th | 5 minutes |
| … | up to 24 hours |
Verifying authenticity
All webhook requests include the header X-Signature:
X-Signature: sha256=5f4dcc3b5aa765d61d8327deb882cf99
- Use your webhook secret token.
- Generate the SHA256 HMAC of the raw payload body.
- Compare with the value in
X-Signature.
This prevents spoofing or man-in-the-middle attacks.
TipIf you’re using a framework that parses JSON before you read the raw body, be sure to extract the raw body for signature verification.
Recommended response
To avoid unnecessary retries, always respond with:
HTTP/1.1 200 OK
Content-Type: application/json
Common pitfalls
| Mistake | How to avoid it |
|---|
| Assuming API response means transaction success. | Always wait for the pix.transaction.status webhook. |
| Forgetting to verify the signature. | Use X-Signature and your webhook secret. |
| Rejecting webhooks due to slow DB or timeout. | Process async if needed, but return 200 quickly. |
| Ignoring duplicate payloads. | Webhooks may be retried. Use transactionId as the idempotency key. |
