跳到正文

知识库 · 阅读约 4 分钟

校验 Webhook 签名

在履行订单之前,检查每个 Webhook 的 ArionPay-Signature 请求头。

校验 Webhook 签名

我们发送的内容

每个 Webhook 都是发往您店铺 Webhook URL 的 JSON POST 请求,带有以下请求头:

  • ArionPay-Event:invoice.pending、invoice.partial、invoice.paid、invoice.expired 或 invoice.needs_review 之一。
  • ArionPay-Event-Id:唯一 ID。请保存它并忽略重复项。
  • ArionPay-Signature:t=<timestamp>,v1=<hex>,其中 v1 是用您店铺的 Webhook 密钥对 <timestamp>.<raw body> 签名得到的 HMAC-SHA256。

履行订单之前

  1. 根据原始请求正文计算签名,并以恒定时间进行比较。
  2. 拒绝过旧的时间戳(我们建议超过 5 分钟即拒绝)。
  3. 利用事件 ID,避免重复投递导致同一订单发货两次。
  4. 通过 data.invoice.id(创建账单时保存)找到订单,并检查 amountFiat 和 currency。
  5. 请在 10 秒内返回 2xx 状态码。其他响应、重定向和超时都会被重试,持续约 3 天。

测试账单的 Webhook 会标记为测试(livemode: false)。在生产环境中,只对 livemode: true 执行操作。Webhook 密钥(whsec_…)不是您的 API 密钥:您可以在 Webhooks 页面通过“Replace secret”获取。

// Node.js
const crypto = require('crypto');

// rawBody: the request body exactly as received (a string), before any JSON parsing
function verifyArionPayWebhook(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=')));
  const ts = parts.t || '';
  const given = parts.v1 || '';
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSec) return false;
  if (!/^[0-9a-f]{64}$/.test(given)) return false;
  const expected = crypto
.createHmac('sha256', secret)
.update(`${ts}.${rawBody}`)
.digest();
  return crypto.timingSafeEqual(expected, Buffer.from(given, 'hex'));
}