事件通知

去我的应用配置

能收到哪些事件

空间管理员在我的应用添加通知地址，每个空间最多 3 个；每个启用的地址都收到本空间的余额不足和密钥异常事件，测试事件只发给点了「发送测试事件」的那个地址。站内消息照常发，推送是另外加的。

ai.credits.low_balance

空间的 AI 额度低于空间管理员设的余额提醒线。没设提醒线（不提醒）的空间不发。

data balanceCredits：当时的余额；alertLineCredits：提醒线。单位都是 Credits。

ai.key.anomaly

空间里一把 API 密钥被停用、过期或用完了用量上限，而不是在 TokenX 里操作的。发到密钥所在空间的地址。

data keyId、label（用途）、prefix（密钥前缀）；reason：disabled 停用、expired 过期、exhausted 用量上限用完。

webhook.test

在「我的应用」点「发送测试事件」。

data endpointId：收到它的地址。

请求格式

每条事件是一个 POST 请求，Content-Type: application/json，请求体如下；createdAt 是事件发生的时间。

{
  "id": "evt_9c1f0b2d4e6a8c0e2f4a6b8d0c2e4f6a",
  "type": "ai.credits.low_balance",
  "createdAt": "2026-09-29T08:00:00.000Z",
  "spaceId": "01K5…",
  "data": { "balanceCredits": 480.5, "alertLineCredits": 500 }
}

X-TokenX-Event-Id: 消息 ID，和请求体里的 id 相同；同一条消息重试时不变
X-TokenX-Event-Type: 事件类型，和请求体里的 type 相同
X-TokenX-Timestamp: 这次发送的时间，Unix 秒；每次重试重新取
X-TokenX-Signature: 签名，小写十六进制，见下方

校验签名

取原始请求体，不要先解析再重新序列化。
检查 X-TokenX-Timestamp 和你的服务器时间相差不超过 5 分钟，挡住重放。
用这个地址的签名密钥（整串，含 whsec_ 前缀）对时间戳 + 换行 + 请求体算 HMAC-SHA256，得到小写十六进制，和 X-TokenX-Signature 做常量时间比较。
每个地址的密钥各不相同，也不是 API 密钥。轮换后立即生效，之后的每次发送（包括重试）都用新密钥签名。

import { createHmac, timingSafeEqual } from "node:crypto";

// secret：添加地址或轮换时显示的签名密钥，整串，含 whsec_ 前缀
// rawBody：收到的原始请求体，不要先解析再重新序列化
function verify(secret, headers, rawBody) {
  const timestamp = headers["x-tokenx-timestamp"];
  if (!/^\d+$/.test(timestamp ?? "")) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${timestamp}\n${rawBody}`).digest("hex");
  const given = Buffer.from(headers["x-tokenx-signature"] ?? "");
  return given.length === expected.length && timingSafeEqual(given, Buffer.from(expected));
}

送达、重试与去重

5 秒内返回 2xx 算送达。其他状态码、跳转（3xx，不跟随）、超时和连不上都算失败。
失败后依次隔 1 分钟、5 分钟、30 分钟、2 小时、6 小时重试，一条消息最多发 6 次，之后不再发。每次发送的结果记在「我的应用」的最近投递里。
重试用同一个消息 ID 和同一个请求体，只有时间戳和签名重新计算。同一条消息可能收到不止一次，按消息 ID 去重：处理过的直接返回 2xx。
不保证先发生的事件先到。
停用的地址不再收到事件，还没送达的也不再重试。
测试事件只发一次，不重试；同一个地址每分钟最多 1 次，每个空间每小时最多 20 次。

地址要求

只支持公网可以访问的 https 地址，证书要有效，地址里不能带用户名和密码。
域名解析出的每个地址都要在公网上：内网、回环、链路本地、100.64.0.0/10 等保留地址都会被拒绝。每次发送前都重新解析、重新检查。
团队和企业空间只有空间管理员能添加、改地址、轮换密钥和停用，每一项都记在操作记录里。