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.received	账户收到 PIX（cash-in 已确认）
pix.completed	PIX 转账发送成功（cash-out）
pix.failed	PIX 转账失败
pix.refund	PIX 退款已处理
pix.med	收到 BACEN 的 MED 通知

安全性

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

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

验证签名

验证签名以确保通知确实由 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 识别），应在不产生重复效果的情况下处理。

端点要求

• URL 必须使用 HTTPS
• 必须在 5 秒内返回 2xx 状态码
• 响应体将被忽略

后续步骤

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