实现

完整示例Copy Anchor Link

以下示例接收交易事件、验证 X-Avista-Signature 签名、快速返回 2xx 并避免重复处理。密钥生成和签名细节请参见 HMAC 签名。

HMAC 签名 (X-Avista-Signature)Copy Anchor Link

在面板中生成签名密钥后，发送到您账户的每个 webhook 都会包含 X-Avista-Signature header，其值为使用该密钥计算的原始请求体的 HMAC-SHA256（十六进制）。验证签名可以确保 webhook 来自 Gateways（而不是发现了您 URL 的第三方），并且 payload 在传输过程中未被篡改。

生成和轮换密钥Copy Anchor Link

密钥只能通过面板（https://<dashboard-host>）生成和轮换；没有对应的 API 端点。

export PIX_API_WEBHOOK_SECRET=<面板中生成的密钥>

轮换时不拒绝传输中的 webhookCopy Anchor Link

轮换会立即替换密钥：此后发送的 webhook 使用新密钥。已在队列中的 webhook 可能仍使用旧密钥签名。因此在切换期间，请在约 30 分钟内同时接受两个密钥：

const SECRETS = [
  process.env.PIX_API_WEBHOOK_SECRET_CURRENT,
  process.env.PIX_API_WEBHOOK_SECRET_PREVIOUS,
].filter(Boolean) as string[];

function isValid(rawBody: Buffer, received: string): boolean {
  const b = Buffer.from(received, 'hex');
  return SECRETS.some((secret) => {
    const a = Buffer.from(
      crypto.createHmac('sha256', secret).update(rawBody).digest('hex'),
      'hex',
    );
    return a.length === b.length && crypto.timingSafeEqual(a, b);
  });
}

此期间过后，移除 PIX_API_WEBHOOK_SECRET_PREVIOUS。在怀疑密钥泄露或进行定期轮换（例如每 90 天）时执行轮换。

如何验证Copy Anchor Link

签名覆盖的正是原始请求体（rawBody，UTF-8），在任何 JSON.parse 之前。如果您重新序列化收到的对象来计算 HMAC，任何差异（键顺序、空格、编码）都会导致签名不匹配。

自定义 headerCopy Anchor Link

URL 上注册的自定义 header（最多 5 个）会随每个 webhook 与签名一起发送。如果您已经在验证自己的 header（例如 Authorization: Basic ...），可以继续验证：X-Avista-Signature 是附加的，不会替代这些 header。

幂等性Copy Anchor Link

对于交易事件，请使用 event + transactionId + status 的组合作为键。这样，同一交易状态变化时会重新处理，而同一事件的重复投递会被忽略。对于 MED 事件，请使用 medId + event。

const key = `webhook:${payload.event}:${payload.transactionId}:${payload.status}`;

const isNew = await redis.set(key, '1', 'EX', 86400, 'NX');

if (!isNew) {
  console.log('Webhook 已处理，忽略');
  return;
}

await processWebhook(payload);

最佳实践Copy Anchor Link

重试Copy Anchor Link

如果您的端点未在 10 秒内返回 2xx（或连接失败），投递将被重试：

响应代码Copy Anchor Link

您的端点应返回合适的 HTTP 代码：

后续步骤Copy Anchor Link