# 接收 Webhook 通知

在购买、续费或余额变化时接收带签名的通知。

## 创建订阅

调用 `POST /webhooks`，传入名称、你的公网 HTTPS 地址、`enabled: true` 和所需的 `event_types`，并发送已保存的 `Idempotency-Key`。密钥需要写入访问权限及 `webhooks:write`。

安全保存返回的签名密钥。使用完整的 `whsec_…` 值，包括前缀。普通订阅读取不会返回密钥。

| 事件 | 含义 |
| --- | --- |
| `fulfillment.updated` | 静态资源或交付状态变化 |
| `renewal.updated` | 续费状态变化 |
| `dynamic.purchase.updated` | 流量购买状态变化 |
| `refund.completed` | 退款完成 |
| `wallet.low_balance` | 钱包余额降至你设置的阈值以下 |

余额提醒还需传入整数字符串 `wallet_low_balance_threshold_fen`。订阅只通知创建后的变化。

## 验证签名

保留原始请求体。使用签名密钥，对时间戳、一个句点和原始请求体字节计算 HMAC-SHA256，再以恒定时间比较 `X-Webhook-Signature`。

以下 Node.js 函数接收 Buffer 类型的 `rawBody` 和 Headers 类型的 `headers`：

```js
import { createHmac, timingSafeEqual } from 'node:crypto';

function verifyWebhook(rawBody, headers, secret) {
  const timestamp = headers.get('X-Webhook-Timestamp') ?? '';
  const signature = headers.get('X-Webhook-Signature') ?? '';
  if (!/^\d+$/.test(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  if (!/^v1=[0-9a-f]{64}$/.test(signature)) return false;
  const expected = createHmac('sha256', secret)
    .update(timestamp + '.')
    .update(rawBody)
    .digest();
  const actual = Buffer.from(signature.slice(3), 'hex');
  return timingSafeEqual(expected, actual);
}
```

验证通过后再解析 JSON。不要先解析再序列化请求体，否则签名字节会改变。

## 处理重复与重试

使用事件的 `id` 避免重复处理。通知可能重复或乱序；需要当前状态时，请读取对应的 API 资源。

安全保存或处理通知后返回 `2xx`。失败通知每轮最多尝试八次，间隔从 30 秒逐步增加至一小时。通过 `GET /webhooks/{id}/deliveries` 查看记录，通过 `POST /webhooks/{id}/deliveries/{delivery}/retry` 重试失败的通知。

## 更换签名密钥

调用 `POST /webhooks/{id}/rotate-secret` 更换密钥。发送中的通知可能仍使用旧密钥，请在接收端保留短暂的过渡时间。接收地址必须是使用 443 端口的公网 HTTPS 地址，且不能重定向。