Webhooks -- 概述

Webhooks 允许您的应用实时接收 Owem Pay 平台上的事件通知。当事件发生时，Owem Pay 会向您注册的 URL 发送 HTTP POST 请求。

工作原理

1. 在您的账户中注册 Webhook URL
2. 当事件发生时（如：收到 PIX），Owem Pay 向您的 URL 发送 HTTP POST
3. 您的应用处理通知并返回 2xx 状态码（200、201 或 204）

可用事件

事件	描述
pix.charge.created	QR Code 已生成（cash-in 待支付）
pix.charge.paid	账户收到 PIX（cash-in 已确认）
pix.charge.expired	QR Code 已过期未支付
pix.payout.created	PIX 转账已创建（cash-out）
pix.payout.confirmed	PIX 转账发送成功
pix.payout.failed	PIX 转账失败
pix.payout.returned	PIX 转账被收款方退回
pix.refund.requested	收到 BACEN 的 MED 退款请求
pix.refund.completed	MED 退款已处理
pix.return.received	收到 PIX 退款
webhook.test	测试事件，用于验证 URL

安全性

每个通知包含安全验证头：

头	描述
X-Owem-Signature	Payload 的 HMAC-SHA256 签名
X-Owem-Timestamp	发送时间戳（ISO 8601）
X-Owem-Event-Id	事件唯一 ID（用于去重）
X-Owem-Event-Type	事件类型（如：pix.charge.paid）

Webhook 使用 SHA256 vs API 使用 SHA512

API 使用 HMAC-SHA512 来验证您发送的请求。Owem Pay 发送的 Webhook 使用 HMAC-SHA256 进行 X-Owem-Signature 签名。它们是不同的算法 -- 各有其使用场景。

验证签名

验证签名以确保通知确实由 Owem Pay 发送：

const crypto = require('crypto');

function validateWebhook(payload, timestamp, signature, secret) {
  const message = `${timestamp}.${payload}`;
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

务必验证

切勿在未验证签名的情况下处理 Webhook。这是防止伪造请求的重要保障。

重试策略

如果您的 URL 返回非 2xx 状态码，Owem Pay 将自动重试：

重试次数	间隔
第 1 次	立即
第 2 次	1 分钟
第 3 次	5 分钟
第 4 次	30 分钟
第 5 次	2 小时

5 次尝试均失败后，该事件将标记为 failed，不再自动重发。

幂等性

您的应用应具备幂等性：如果多次收到同一事件（通过 X-Owem-Event-Id 识别），应在不产生重复效果的情况下处理。

Webhook 中的 External ID

当交易创建时包含 external_id，该字段会包含在 Webhook payload 的 data 对象中。使用它可以直接将事件与您系统中的订单关联，无需额外查询。

端点要求

• URL 必须使用 HTTPS（除非注册时设置了 allow_insecure: true）
• 必须在 5 秒内返回 2xx 状态码
• 响应体将被忽略

后续步骤

• 注册 Webhook -- 创建、查询和删除 Webhooks
• 事件 Payload -- 各事件类型的示例