Webhooks

Saq 的 webhook 系统实时发送您交易状态变更 的通知。当您创建一笔交易 并提供 callbackUrl 时,我们的系统会在每次状态变更时 向该 URL 发送更新。

什么是 webhook(callback)

webhook(也称为 callback)是一个 POST 请求,当某些事件发生时 由 Saq 发送到您的服务器。与普通 API(您调用 Saq)相反,这里是反向的:Saq 调用您。

设想一笔 Pix 收款。您创建了订单,向客户展示了 QR Code,现在需要知道客户何时付款。有两种方式:

1. 轮询,每隔 X 秒询问一次"付了吗?付了吗?"(成本高、慢、不必要)。
2. webhook,让 Saq 在付款到账时通知您(即时、高效、推荐)。

如何配置

没有单独的"注册 webhook"endpoint。URL 在 每次创建交易时 通过 body 中的 callbackUrl 字段提供:

{
  "amount": 99.90,
  "callbackUrl": "https://seusite.com.br/webhooks/saq",
  "clientReference": "pedido-2025-001"
}

Saq 会在 该交易每次状态变更时(PENDING → COMPLETED、COMPLETED → REFUNDED 等)向该 URL 发送 callback。

重试机制

Saq 的 webhook 具有强大的重试机制,即使在临时故障时 也能确保送达。Saq 会以指数退避加抖动的方式 最多重发 72 次 相同的 callback,从而更好地分散 负载并避免请求峰值。

安全

为保证完整性与安全性,请 限制访问 您的 webhook endpoint。请向支持团队索取 Saq 的 官方 IP,并仅接受来自该来源的 callback。

payload 字段

标识

状态与金额

生成的收款(存款)

付款方

收款方

通过 Pix 密钥提现

清算与退款

时间戳

违规(Pix 争议)

最佳实践

• 快速响应:在 5 秒内返回 2xx。重处理交给 队列/worker,不要放在 handler 中。
• 幂等性:存储 id + status 以进行去重。同一个 callback 可能会到达多次(重试、连续状态变更)。
• 使用 clientReference:创建交易时传入 外部标识。会在 callback 中返回,便于与您的订单关联。
• 按 IP 限制:仅接受来自 Saq 官方 IP 的 callback。

查询与重发

API 暴露了已发送 callback 的完整列表:

• GET /user/callbacks,分页列表
• GET /user/callbacks/{id},详情
• POST /user/callbacks/resend/{transactionId},重发某笔交易的 callback
• POST /user/callbacks/resend,批量重发