Webhook 事件与签名验证

本文旨在协助负责实现 Webhook 接收端的工程师，重点说明如何验证 X-Kanorio-Signature 签名、如何执行幂等去重，以及如何利用 cacheTags 触发外部前端缓存更新。

• 若您需要在后台新增 Webhook 地址、选择订阅事件（支持商务版依特定集合 collectionKeys 或表单 formIds 过滤）或查看投递记录，请参阅Webhook 设置与管理。
• 完整事件列表与 data 字段规格（SSOT）：所有可订阅事件的代码、所需权限与 data JSON 示例，均由系统事件注册表自动生成于 Webhooks 参考页。

HTTP 请求格式与接收端四原则

每则 Webhook 通知皆以 HTTPS POST 发送，Content-Type 为 application/json，并附带以下 Headers：

接收端实现要点

1. 在超时前先返回 2xx： 接收端返回任何 2xx（如 200 OK、202 Accepted）即视为投递成功。若后续处理（如同步外部数据库或触发长耗时工作）较慢，请在验签与写入队列后先立即返回 200，再于后台异步处理。
2. 不跟随 3xx 重定向： Kanorio 发送 Webhook 时不会跟随任何 3xx 重定向（收到 301、302、307、308 一律视为投递失败）。请确认设置在后台的地址即为最终端点（留意结尾斜线 / 是否会触发框架自动跳转）。
3. 重试与自动暂停： 网络错误、超时、HTTP 429 或 5xx 会自动进入指数退避重试；410 Gone 会立即停用该端点；连续失败超过上限时系统会自动暂停端点并通知团队。
4. 以 X-Kanorio-Delivery 做幂等去重： 网络重试或后台手动重送时，同一则通知可能送达超过一次。请以 X-Kanorio-Delivery（或 JSON 顶层的 id） 作为唯一键去重；若已处理过，直接返回 200 OK。

验证签名（X-Kanorio-Signature）

自建接收端时，请务必使用后台该端点的“签名密钥”（whsec_...）验证 X-Kanorio-Signature，确认请求来自 Kanorio 且内容未被篡改：

1. 解析 Header：将 X-Kanorio-Signature 以逗号 , 分割，取出 t= 后方的 Unix 秒数时间戳，以及所有 v1= 后方的十六进制签名字符串（密钥轮替的 24 小时并行期内会有两个 v1）。
2. 检查时间戳防重放：比对 t 与服务器当前时间，若相差超过 5 分钟（300 秒） 请直接拒绝（每次重试都会以当前时间重新计算 t 与签名）。
3. 组合待签字符串：将时间戳 t、英文句点 . 与未经解析的原始请求字符串（Raw Request Body）串接为 {t}.{rawBody}。
4. 以常数时间比对 HMAC-SHA256：以 whsec_... 密钥对 {t}.{rawBody} 计算 HMAC-SHA256 十六进制摘要，并以 crypto.timingSafeEqual 比对是否与任一个 v1 相符。

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

export function verifyKanorioWebhook(rawBody, signatureHeader, secret) {
  if (!signatureHeader || !secret) return false;

  const parts = signatureHeader.split(",").map((part) => part.split("="));
  const t = parts.find(([key]) => key === "t")?.[1];
  const signatures = parts
    .filter(([key]) => key === "v1")
    .map(([, value]) => value)
    .filter(Boolean);

  if (!t || signatures.length === 0) return false;

  const timestampSec = Number(t);
  if (!Number.isFinite(timestampSec) || Math.abs(Date.now() / 1000 - timestampSec) > 300) {
    return false;
  }

  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const expectedBuf = Buffer.from(expected, "utf8");

  return signatures.some((v1) => {
    const v1Buf = Buffer.from(v1, "utf8");
    return v1Buf.length === expectedBuf.length && timingSafeEqual(expectedBuf, v1Buf);
  });
}

Payload 共同外壳与 cacheTags 缓存更新

所有 Webhook 事件皆采用相同的顶层 JSON 外壳，事件专属字段放在 data 内：

{
  "version": "1",
  "id": "3f9c2a8b1e4d7c0f9a2b3c4d5e6f7a8b",
  "event": "collections.item.published",
  "occurredAt": "2026-10-21T08:30:00.000Z",
  "websiteId": "cmk1examplewebsiteid",
  "title": "Collection item published: Sourdough Guide",
  "summary": "blog/sourdough-guide (published)",
  "data": {
    "collectionId": "col_01",
    "collectionKey": "blog",
    "itemId": "item_01",
    "slug": "sourdough-guide",
    "status": "published",
    "publicVersion": "1729500000000",
    "cacheTags": ["site:cmk1examplewebsiteid", "collection:blog", "item:item_01"]
  },
  "actionUrl": "https://app.kanorio.com/data/blog"
}

配合 data.cacheTags 做按需缓存更新（ISR）

所有内容与集合变更事件（collections.item.*、collections.items.bulkChanged、collections.schema.changed、content.page.*、content.site.published）的 data 都会附上 publicVersion 与 cacheTags（对齐 Content Delivery API 响应 Header 的 X-Kanorio-Cache-Tags）：

• 当页面改名时，content.page.updated 会额外附上 previousSlug 并将 redirects 加入 cacheTags，让您的外部前端同时失效旧路径与重定向缓存。
• 在 Next.js Route Handler 中，只要验签通过后对 payload.data.cacheTags 逐一调用 revalidateTag(tag)，即可在数秒内精准更新受影响的页面（完整示例见）。

相关文档