Webhook

从 Pix Processamento 接收事件有两种方式：

交易上的 callbackUrl：在每次 POST /pix、POST /withdraw 或 POST /internal-transfer 时传入 URL。简单，无需注册，也没有签名。
已注册的 Webhook（本章节）：只注册一次 URL，选择想接收的事件，并在请求头中获得 HMAC 签名。这是推荐方式。

两者可以共存：如果交易带了 callbackUrl，且账户有启用的 Webhook，两边都会收到。

该用哪一个

问题	端点
我想注册 URL 并接收事件	`POST /user/webhooks`
我的账户注册了哪些 Webhook？	`GET /user/webhooks`
这个 Webhook 是否启用？订阅了什么？	`GET /user/webhooks/{id}`
我想换 URL、暂停或修改订阅的事件	`PATCH /user/webhooks/{id}`
我想彻底删除它	`DELETE /user/webhooks/{id}`
密钥泄露了，需要新的	`POST /user/webhooks/{id}/rotate-secret`
一共推送了多少次？	`GET /user/webhooks/sent/quantity`
那次推送具体发了什么，我回了什么？	`GET /user/webhooks/{id}/sent/{callbackId}`
我的端点宕机了，想重发失败的推送	`POST /user/callbacks/resend/webhook/{webhookId}`

secret 只显示一次：在 POST /user/webhooks（generateSecret: true）和 POST /user/webhooks/{id}/rotate-secret 的响应中。之后没有任何端点可以读取它。丢失了就轮换一个新的。

每个账户最多 5 个启用的 Webhook。超出后创建或重新启用会返回 409 Conflict。已停用的 Webhook 不计入。

发送 events: []（或省略该字段）表示订阅全部事件。

事件	触发时机
`TRANSACTION_PENDING`	交易已创建，等待付款
`TRANSACTION_COMPLETED`	交易已结算
`TRANSACTION_CANCELED`	交易已取消
`TRANSACTION_WAITING_FOR_REFUND`	已申请退款，等待处理
`TRANSACTION_REFUNDED`	退款已完成
`TRANSACTION_EXPIRED`	收款码未付款即过期
`TRANSACTION_ERROR`	交易以错误结束
`TRANSACTION_SUSPECTED_FRAUD`	交易被标记为疑似欺诈
`TRANSACTION_SUSPECTED_FRAUD_REVERSAL`	疑似欺诈标记被撤销
`INFRACTION_CHANGED`	与交易关联的 MED 违规状态发生变化

每次推送的事件类型放在 X-Callback-Event 请求头中。完整负载和签名校验见 Webhook。