Webhook

当网站发生特定事件时，Kanorio 可实时通知您的系统：买家付款、包裹出货或送达、访客提交表单、寄件域名失效、寄送额度用尽、流量突破里程碑等。通过连接 Zapier、Make、n8n 或您自建的程序，即可自动将数据写入电子表格、转发至团队聊天群组、建立客服工单，或同步至您的 ERP 与 CRM 系统。

您可在网站主控台的技术设置中的“串接”分页进行设置。Webhook 为商务版功能，仅限网站拥有者与管理员新增或管理；其他成员无法查看网址、密钥及推送记录。

新增 Webhook

1. 在接收端建立一个接收网址。例如在 Zapier 选择“Webhooks by Zapier”的“Catch Hook”，Make 选择“Webhooks”的“Custom webhook”，或在 n8n 新增“Webhook”节点。网址必须以 https:// 开头。
2. 前往主控台的“技术设置”，切换至“串接”分页。
3. 点击“新增 Webhook”并粘贴网址。您可以为其命名，例如“Zapier 订单流程”，以便识别。
4. 点击“新增 Webhook”。系统将显示该端点的“签名密钥”，若需验证请求来源，请将其复制并设置至接收端（详见下方“给工程师”）。
5. 点击“发送测试”。当接收端收到“Kanorio 测试事件”且画面显示响应状态码与耗时，即代表连接成功。

每个网站最多可新增 5 个 Webhook。

选择要发送的事件

展开每个端点后，皆可设置“订阅事件”：

• 全部事件（默认）：发送目前所有事件，日后新增的事件亦会自动发送。
• 指定事件：仅勾选您需要的事件，并点击“保存订阅”。

目前支持的事件如下（字段细节请见文末“事件参考”）：

Webhook 的发送与否仅取决于此处的订阅设置。自动通知各情境面板虽会显示“N 个端点已订阅”或“尚未连接”，但开关控制权在于此处。

Webhook 不会取代寄给您的 Email。启用 Webhook 后，原本寄给拥有者的通知信（如新订单与表单回复）仍会正常发送；货态更新的团队 Email 默认是关闭的。若需调整团队 Email，请至“自动通知”设置。

发送失败时的处理

• 若接收端响应错误（HTTP 429 或 5xx）或 8 秒内无响应，Kanorio 将自动重试：1 分钟、5 分钟、30 分钟、2 小时、8 小时、24 小时后，以及再 24 小时后，总共最多重试 8 次，历时约两天半。
• 若接收端响应其他 4xx 错误（如 404、401），代表设置有误，系统将不会重试。
• 若接收端响应 410 Gone，代表您不愿再接收，该端点将立即暂停。
• 若连续 3 次通知发送失败（重试用尽），该端点将自动暂停，以避免持续发送至失效网址。拥有者与管理员将收到通知。
• 确认接收端恢复正常后，请展开该端点，先点击“发送测试”，成功后点击“重新启用”。

展开每个端点即可查看“最近推送”记录：包含事件、结果、HTTP 状态与时间；展开单笔记录可查看尝试次数、耗时、下次重试时间与错误原因。7 天内的通知可“查看内容”以检视发送数据，亦可点击“重送”再次发送；重送将使用相同的通知编号，接收端可据此判断是否重复。

“发送测试”不会计入失败次数，排查问题时可放心多次测试。

接收端设有防火墙时

Kanorio 会从固定的 IP 发送 Webhook。若您的接收端仅允许白名单来源，请将以下三个 IPv4 全部加入（首次发送、测试与手动重送来自前两个，自动重试来自第三个）：

白名单仅为额外防护，无法取代签名验证：请务必验证 X-Kanorio-Signature（详见下方“给工程师”）。若 IP 需变更，我们会先在此公告，并保留新旧 IP 并行一段时间后再移除旧 IP。

给工程师

请求格式

每则通知皆为 POST 请求，Content-Type: application/json，并附带以下 header：

接收端响应任何 2xx 即视为成功，响应内容不会被读取。请在 8 秒内响应；若需较长处理时间，请先回传 200 再进行异步处理。Kanorio 不会跟随重定向，3xx 将视为失败。

共同结构

所有事件的 JSON 结构相同，接收端仅需设置一次：

{
  "version": "1",
  "id": "3f9c2a…",
  "event": "ec.order.paid",
  "occurredAt": "2026-09-29T12:00:00.000Z",
  "websiteId": "cmk…",
  "title": "新订单 #1024，NT$1,280",
  "summary": "「我的商店」收到一笔已付款的订单。",
  "fields": [{ "label": "订单编号", "value": "#1024" }],
  "data": { "…": "依事件而异，见下方事件参考" },
  "actionUrl": "https://app.kanorio.com/store/transactions?tx=…"
}

事件参考

以下为各事件的 data 字段。“可空”表示该字段可能为 null。

ec.order.paid 订单付款

买家完成付款、订单成立时发送；每笔订单发送一次。

ec.shipment.statusChanged 货态更新

出货单进入出货、到店、送达或配送异常时发送；同一张出货单的每个货态各发送一次。

customers.form.submitted 表单回复

访客提交表单且通过垃圾判定时发送；每笔回复发送一次。

answers[] 的每一项：

customers.sendingDomain.degraded 寄件域名失效

已验证的自有寄件域名验证失效时发送；同一个域名每天最多发送一次。

customers.messagingQuota.alert 寄送额度提醒

寄送额度状态变更时发送。

site.analytics.milestone 流量里程碑

网站累计浏览量突破里程碑时发送，每个里程碑发送一次。

customers.teamDestination.disabled 串接暂停

某个 Webhook 端点被自动暂停时发送（连续失败达门槛或接收端回传 410）。仅会发送至其他正常的端点。

team.test 测试事件

点击“发送测试”时发送，仅发送一次、不重试、不写入推送记录。

确认请求来自 Kanorio

验证方式：

1. 从 X-Kanorio-Signature 取出 t 与所有 v1。
2. 将 t、一个英文句点与原始请求内容（未经解析、重新序列化的 raw body）串接，例如 1790000000.{"version":"1",…}。
3. 使用签名密钥对该字符串计算 HMAC-SHA256（十六进制），并与任一个 v1 比对，相符才接受。
4. 时间戳与当前时间相差超过 5 分钟的请求请直接拒绝，以防重播攻击。重试与重送皆会使用当下时间重新签名，无需放宽此限制。

Node.js 示例：

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

function verify(rawBody, header, secret) {
  const parts = header.split(",").map((part) => part.split("="));
  const t = parts.find(([key]) => key === "t")?.[1];
  const signatures = parts.filter(([key]) => key === "v1").map(([, value]) => value);
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return signatures.some(
    (v1) => v1.length === expected.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1))
  );
}

Zapier、Make、n8n 等服务通常无处编写验证逻辑；其接收网址本身包含随机路径，通常不需额外验证签名。

更换签名密钥

签名密钥可在串接列表展开该端点后，点击“显示”查看。若怀疑密钥外流，请点击“产生新密钥”：

• 旧密钥在 24 小时内仍有效，期间每则请求会同时附上新旧两个签名（两个 v1），任一相符即可。
• 请于 24 小时内将接收端更新为新密钥。面板将显示旧密钥的到期时间。
• 若于 24 小时内再次点击“产生新密钥”，旧密钥将立即失效。

相关文档

• 开发者
• 自动通知
• 记录：查看每一次寄给顾客与团队的通知
• 方案比较