The Pix plugin uses webhooks to notify your system of important events related to transactions, keys, and external messages.

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)

❗️

Important

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"
}

👍

Tip

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.

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.

👍

Tip

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.

Recommended response

---

To avoid unnecessary retries, always respond with:

HTTP/1.1 200 OK
Content-Type: application/json

Optionally, you can return:

{ "status": "received" }

Common pitfalls

---