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)
If 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"
}
FieldDescription
typeEvent type (pix.transaction.status)
transactionIdYour transaction identifier.
statuspending, confirmed, failed, or reversed
amountTransaction amount.
updatedAtTime of final status confirmation.
Use 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"
}
This type of webhook is optional but helpful for:
  • 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"
}
This ensures you can:
  • 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.
AttemptDelay before retry
1stImmediate
2nd10 seconds
3rd1 minute
4th5 minutes
…up to 24 hours

​
Verifying authenticity

All webhook requests include the header X-Signature: 
X-Signature: sha256=5f4dcc3b5aa765d61d8327deb882cf99
To validate:
  • 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.
If you’re using a framework that parses JSON before you read the raw body, be sure to extract the raw body for signature verification.
To avoid unnecessary retries, always respond with: 
HTTP/1.1 200 OK
Content-Type: application/json
Optionally, you can return: 
{ "status": "received" }

​
Common pitfalls

MistakeHow 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.