Overview

What are Webhooks?

PIX Webhooks allow you to receive real-time notifications when the status of a PIX transaction changes. Instead of constantly polling the API, your system is automatically notified when important events occur.

Webhooks are the recommended way to track transaction statuses. They reduce latency and resource consumption compared to polling.

Features

Real-time notifications
Support for 4 event types (Cash In, Cash Out, Refund In, Refund Out)
Automatic retries on failure
Basic Auth authentication
Standardized JSON payload

Available Events

CashIn

PIX receipt confirmed (CREDIT)

CashOut

PIX send confirmed (DEBIT)

CashInReversal

Receipt reversal (DEBIT)

CashOutReversal

Send reversal received (CREDIT)

Event	`event`	`movementType`	Description
PIX In	`CashIn`	`CREDIT`	PIX receipt confirmed
PIX Out	`CashOut`	`DEBIT`	PIX send confirmed
Refund In	`CashInReversal`	`DEBIT`	Receipt reversal (refund initiated by you)
Refund Out	`CashOutReversal`	`CREDIT`	Send reversal (refund received)

Endpoint Configuration

To receive webhooks, you need to:

Use the Webhook Configuration API to define your endpoint URL programmatically.

Create an HTTPS endpoint that accepts POST requests and returns HTTP 200 quickly.

Configure Basic Auth header validation.

Technical Requirements

Requirement	Description
Protocol	HTTPS mandatory
Method	POST
Timeout	Respond within 10 seconds
Response	HTTP 200 OK
Content-Type	application/json

If your endpoint does not respond with HTTP 200 within 10 seconds, the webhook will be considered a failure and will be retried.

Basic Auth Authentication

Webhooks are sent with Basic Auth authentication in the header:

Authorization: Basic base64(username:password)

// Node.js/Express - Validation
app.post('/webhooks/pix', (req, res) => {
  const authHeader = req.headers.authorization;

  if (!authHeader || !authHeader.startsWith('Basic ')) {
    return res.status(401).send('Unauthorized');
  }

  const base64Credentials = authHeader.split(' ')[1];
  const credentials = Buffer.from(base64Credentials, 'base64').toString('ascii');
  const [username, password] = credentials.split(':');

  if (username !== process.env.WEBHOOK_USER || password !== process.env.WEBHOOK_PASS) {
    return res.status(401).send('Unauthorized');
  }

  // Process webhook...
  res.status(200).json({ acknowledged: true });
});

Base Payload Structure

All webhooks share a common base structure:

{
  "event": "CashIn",
  "status": "CONFIRMED",
  "transactionType": "PIX",
  "movementType": "CREDIT",
  "transactionId": "12345",
  "externalId": "PIX-5482123298-EJUYFSMU1UU",
  "endToEndId": "E00416968202512111942rjzxxzSSTD9",
  "pixKey": "1ff6ce09-4244-44d5-aa8f-1fe69f8986a9",
  "feeAmount": 0.01,
  "originalAmount": 0.5,
  "finalAmount": 0.49,
  "processingDate": "2025-12-11T19:42:04.080Z",
  "errorCode": null,
  "errorMessage": null,
  "metadata": {}
}