概述

什么是 Webhooks？

PIX Webhooks 允许您在 PIX 交易状态发生变化时实时接收通知。您的系统无需持续轮询 API，而是在重要事件发生时自动收到通知。

Webhooks 是追踪交易状态的推荐方式。与轮询相比，它们能降低延迟和资源消耗。

功能特性

实时通知
支持 4 种事件类型（Cash In、Cash Out、Refund In、Refund Out）
失败时自动重试
Basic Auth 认证
标准化 JSON 负载

可用事件

CashIn

PIX 收款已确认 (CREDIT)

CashOut

PIX 付款已确认 (DEBIT)

CashInReversal

收款退款 (DEBIT)

CashOutReversal

付款退回 (CREDIT)

事件	`event`	`movementType`	描述
PIX 收款	`CashIn`	`CREDIT`	PIX 收款已确认
PIX 付款	`CashOut`	`DEBIT`	PIX 付款已确认
收款退款	`CashInReversal`	`DEBIT`	收款退回（由您发起的退款）
付款退回	`CashOutReversal`	`CREDIT`	付款退回（收到的退款）

端点配置

要接收 webhooks，您需要：

使用 Webhook 配置 API 以编程方式定义您的端点 URL。

创建一个接受 POST 请求并快速返回 HTTP 200 的 HTTPS 端点。

配置 Basic Auth 请求头验证。

技术要求

要求	描述
协议	必须使用 HTTPS
方法	POST
超时	10 秒内响应
响应	HTTP 200 OK
Content-Type	application/json

如果您的端点未在 10 秒内响应 HTTP 200，webhook 将被视为失败并进行重试。

Basic Auth 认证

Webhooks 在请求头中使用 Basic Auth 认证发送：

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 });
});

基础负载结构

所有 webhooks 共享一个通用的基础结构：

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