API Endpoints
Webhooks
There are two ways to receive events from Pix Processamento:
callbackUrlon the transaction, you pass the URL on everyPOST /pix,POST /withdraworPOST /internal-transfer. Simple, no registration, no signature.- Registered webhook (this section), you register the URL once, choose which events you want, and get an HMAC signature in the header. This is the recommended path.
Both coexist: if the transaction has a callbackUrl and the account has active webhooks, both receive the event.
POSTCreate webhookGETList webhooksGETGet webhookPATCHUpdate webhookDELETEDelete webhookPOSTRotate secretGETCount deliveriesGETDelivery detail
Which one to use
| Question | Endpoint |
|---|---|
| I want to register my URL and receive events | POST /user/webhooks |
| Which webhooks are registered on my account? | GET /user/webhooks |
| Is this webhook active? Which events does it subscribe to? | GET /user/webhooks/{id} |
| I want to change the URL, pause it, or change the events | PATCH /user/webhooks/{id} |
| I want to remove it for good | DELETE /user/webhooks/{id} |
| The secret leaked, I need a new one | POST /user/webhooks/{id}/rotate-secret |
| How many deliveries went out? | GET /user/webhooks/sent/quantity |
| What exactly was sent, and what did I answer? | GET /user/webhooks/{id}/sent/{callbackId} |
| My endpoint was down, I want to re-send what failed | POST /user/callbacks/resend/webhook/{webhookId} |
The secret is shown only once: in the response of POST /user/webhooks (with generateSecret: true) and in the response of POST /user/webhooks/{id}/rotate-secret. There is no endpoint to read it later. If you lose it, rotate it.
Limit of 5 active webhooks per account. Creating or re-enabling beyond that returns 409 Conflict. Inactive webhooks do not count.
Subscribable events
Sending events: [] (or omitting the field) subscribes to every event.
| Event | Fires when |
|---|---|
TRANSACTION_PENDING | Transaction created and awaiting payment |
TRANSACTION_COMPLETED | Transaction settled |
TRANSACTION_CANCELED | Transaction canceled |
TRANSACTION_WAITING_FOR_REFUND | Refund requested, awaiting processing |
TRANSACTION_REFUNDED | Refund completed |
TRANSACTION_EXPIRED | Charge expired without payment |
TRANSACTION_ERROR | Transaction ended in error |
TRANSACTION_SUSPECTED_FRAUD | Transaction flagged as suspected fraud |
TRANSACTION_SUSPECTED_FRAUD_REVERSAL | Suspected-fraud flag reverted |
INFRACTION_CHANGED | A MED infraction linked to a transaction changed status |
The event of each delivery is sent in the X-Callback-Event header. See the full payload and signature verification in Webhooks.