Webhook 设置与管理
当您的网站上有事情发生时 - 例如买家完成支付、包裹出货或送达、访客提交联系表单、发件域名验证失效或流量突破里程碑 - Kanorio 可以通过 Webhook 主动把该笔资料实时送到您指定的网址。
把 Webhook 接上 Zapier、Make、n8n 或您自建的系统后,就能免手动把新订单写进 Google 表格、把客户填表内容转发到团队的 Slack/Discord/Telegram 群组、自动建立客服工单,或同步到公司的 ERP 与 CRM。
如果您是负责编写接收程序的工程师: 本篇说明后台设置、事件订阅、重试规则与失败排查;若要查看 HTTP Headers、
X-Kanorio-Signature签名验证代码与 8 种事件的完整 JSON 字段规格,请直接阅读Webhook 事件与签名验证。
开始前请先确认
- 设置位置:后台左侧「网站设置 › 开发者 › Webhooks」。
- 端点数量:所有计划(含免费版、专业版与商务版)每个网站最多皆可建立 10 个 Webhook 端点。
- 角色权限:只有网站的拥有者与管理员可以新增、测试、修改订阅、查看送出内容、手动重送与显示/轮替签名密钥;其他团队成员只看得到端点的显示名称与状态,看不到网址、密钥与推送记录。
新增与测试 Webhook(5 个步骤)
1. 在接收工具取得 HTTPS 接收网址
先打开您用来接收资料的工具,建立一个 Webhook 接收端并复制网址(网址必须以 https:// 开头,且不能是 localhost 或内部网络地址):
- Zapier:新增 Zap,Trigger 选「Webhooks by Zapier」→ Event 选「Catch Hook」,复制产生的 Webhook URL。
- Make:新增 Scenario,第一个模块选「Webhooks」→「Custom webhook」,新增并复制网址。
- n8n:新增「Webhook」节点,HTTP Method 选
POST,复制 Production/Test URL。 - 自建系统:由您的工程师提供一个可接收
POSTJSON 请求的https://网址。
2. 在 Kanorio 新增端点
前往「网站设置 › 开发者 › Webhooks」,点击「新增 Webhook」,粘贴刚才复制的网址,并填入一个好辨识的显示名称(例如「Zapier 订单同步表格」「Make 表单转发群组」),再按「新增 Webhook」。
3. 复制或保存签名密钥
建立完成后,画面会显示这个端点专属的「签名密钥」(以 whsec_ 开头):
- 如果您接的是 Zapier、Make、n8n:这类工具的接收网址本身带有随机密钥路径,通常不需要另外设置签名验证,直接按「完成」即可。
- 如果您接的是自建服务器:请复制这把签名密钥交给您的工程师设置验签(之后随时可在列表展开该端点、点击「显示」再次查看,或点击「产生新密钥」轮替)。
4. 点击「发送测试」确认连通
在列表中点开刚建立的端点,按「发送测试」。系统会立即送出一则测试事件(team.test):
- 画面显示「测试成功(HTTP 200,耗时 X ms)」,且您的 Zapier/Make 或服务器收到测试资料,就代表连线成功。
- 「发送测试」不会写入正式推送记录,也不会计入连续失败次数,排查时可以放心多按几次。
5. 调整要订阅的事件(选用)
新建立的端点默认会订阅「全部事件」;若只想让这个网址收到特定通知(例如只收「订单支付」),请见下一节调整。
选择要订阅的事件
在列表展开任一端点,于「订阅事件」区块可选择:
- 全部事件(默认):目前支持的所有事件都会送出,未来 Kanorio 新增的事件也会自动送出。
- 指定事件:只勾选这个端点需要的事件(至少勾选一项),按「保存订阅」立即生效。
目前支持以下正式运营事件与 1 种测试事件(各事件的 JSON 字段细节请见Webhook 事件与签名验证):
| 事件名称 | 什么时候会送出? | 事件代码 |
|---|---|---|
| 订单付款 | 买家完成付款、订单正式成立时(每笔订单送出一次) | ec.order.paid |
| 货态更新 | 出货单进入已出货、已到店、已送达或配送异常时 | ec.shipment.statusChanged |
| 表单回复 | 访客送出在线表单且通过防灌水检查时(含填表人信息与每一题完整答案) | customers.form.submitted |
| 存取权开通/撤销 | 学员因购买、免费领取或您手动开通而取得课程或下载包,或存取权被撤销时 | deliverables.entitlement.granted / revoked |
| 单元完成 | 学员完成课程中的一个单元时(每位学员每个单元送出一次) | deliverables.progress.unit_completed |
| 课程完成 | 学员达到课程的完成条件时(每位学员每门课送出一次) | deliverables.progress.completed |
| 测验作答 | 学员交出测验时(含分数与是否及格) | deliverables.quiz.attempted |
| 发出结业证书 | 学员取得结业证书(记下证书编号与发证日期)时;每位学员每门课一次 | deliverables.certificate.issued |
| 数据集合项目变更 | 数据集合单笔项目新增、更新草稿、发布、取消发布或删除时 | collections.item.created / updated / published / unpublished / deleted |
| 数据集合批次变更 | 在后台工作台批次保存、导入 CSV/JSON,或透过 API 批次写入数据集合项目时(合并送出一则) | collections.items.bulk_changed |
| 译文上线/移除 | 多语言网站某一笔内容在某个语言的译文单独上线(校正后保存、API 写入、原文改动后的自动补翻)或被移除时;整站翻译进行中不会逐笔送出 | content.translation.published / deleted |
| 语言上线/下线/更新 | 某个语言对访客上线(整站翻译完成或您手动上线)、被移除或停用,或改了网址前缀、自动翻译开关、顺序或主语言时 | localization.locale.published / unpublished / updated |
| 整站翻译完成/失败 | 加入语言或「重跑缺的」启动的整站翻译结束时(附翻好、略过与失败的笔数) | localization.job.completed / failed |
| 寄件域名失效 | 您已验证的自有寄件域名 DNS 验证失效时(同一域名每天最多一次) | customers.sendingDomain.degraded |
| 寄送额度提醒 | 本期寄信额度用完、触发自动加购、自动加购达上限或加购扣款失败时 | customers.messagingQuota.alert |
| 存储空间提醒 | 存储空间快满、已满、触发自动加购、自动加购达上限或加购扣款失败时 | site.storageQuota.alert |
| 年度续订提醒 | 年缴计划续订前,且有年缴加购或尚未结算的加购费、平台费时(预告合并扣款总额) | site.subscription.upcomingRenewal |
| 加购调价预告 | 加购项目定价调整前(至少提前 30 天) | site.subscription.addOnPriceChange |
| 流量里程碑 | 网站累计浏览量突破 100、500 时 | site.analytics.milestone |
| 串接暂停 | 某个 Webhook 端点因连续失败被系统自动暂停时(会通知其他仍正常的端点,不会送给被暂停的那个端点) | customers.teamDestination.disabled |
| 权限申请 | 团队成员在后台遇到权限不足、送出权限申请时(每笔申请送出一次) | team.accessRequest.created |
| 测试事件 | 在面板点选「传送测试」时 | team.test |
Webhook 与「团队通知 Email」的分工
- 开关独立管理:要不要送出 Webhook,只看「网站设置 › 开发者 › Webhooks」里各端点的订阅设置。「自动化 › 设置」点开自动化后,「送出 Webhook」会显示「N 个端点已订阅」或「尚未连接」供您核对,但开关统一在 Webhooks 页面设置。
- 不会取代原本的团队 Email:新增 Webhook 后,原本会寄给网站拥有者或团队名单的通知信(例如新订单、表单回复)照样会寄出。若想关闭团队 Email、只留 Webhook,请至「购物通知」或「表单确认信」将团队 Email 开关关闭。
- 不占用寄信额度:Webhook 是通过 HTTPS 直接推送到外部网址,完全不消耗网站每月的 Email 寄送额度。
查看推送记录、手动重送与自动暂停恢复
查看最近推送与「重送」
展开任一端点,下方的「最近推送」会列出最近 10 笔通知的事件名称、结果状态(已送出、失败、处理中)、HTTP 状态码与时间;点开单笔记录可进一步查看尝试次数、耗时、下次自动重试时间与失败原因:
- 查看内容(保存 7 天):通知送出后的 7 天内,您可以点击「查看内容」检视当时送出的完整 JSON 资料。
- 手动重送(保存 7 天):若接收端曾短暂故障或流程设置刚修好,7 天内的通知随时可点击「重送」再推送一次。手动重送会使用相同的通知编号(方便接收端去重),且如果重送失败,不会触发后台重试、也不会计入自动暂停的失败次数。
送不出去时的自动重试与自动暂停
当您的接收端没有正常响应时,系统会依响应状态自动处理:
- 自动退避重试(最多 8 次、约两天半):
如果接收端超过 8 秒没有响应、发生网络错误,或回传 HTTP
429(请求太频繁)、5xx(服务器错误),Kanorio 会在后台依序自动重试:1 分钟后 → 5 分钟后 → 30 分钟后 → 2 小时后 → 8 小时后 → 24 小时后 → 再 24 小时后,加上首次送出总共最多尝试 8 次。 - 不重试的错误(
3xx与其他4xx): 如果接收端回传重定向(301、302等)或设置错误(如400、401、403、404),代表网址或验证设置有问题,系统不会重试,直接计为 1 次推送失败。 - 立即暂停(
410 Gone): 如果接收端回传410 Gone,代表对方明确宣告该网址已停用,系统会立即暂停这个端点。 - 连续 3 次失败自动暂停:
当某个端点连续 3 则通知最终都送不出去(例如重试 8 次用尽仍失败,或连续 3 次收到
404),系统会将该端点标为「连续失败,已暂停」,停止继续推送,并寄送平台通知与 Email 给具「管理串接服务」权限的成员(拥有者、管理员,以及勾选此权限的自定义角色)。 - 如何重新启用: 确认接收端(或 Zapier/Make 流程)修复后,回到「网站设置 › 开发者 › Webhooks」展开该端点,先按「发送测试」确认响应正常,再按「重新启用」即可恢复推送(失败计数会自动归零)。
常见推送失败原因与排查方式
在「发送测试」或「最近推送」看到失败信息时,可对照下表快速排查:
| 后台显示的失败原因 | 代表什么意思? | 建议处理方式 |
|---|---|---|
| 接收端超过 8 秒没有回应 | 接收端处理太久才回传结果 | 请工程师将接收端改为「收到请求验证无误后先回传 200 OK,再于后台处理后续耗时工作(如写入数据库或寄信)」 |
| 接收端回应了重定向,Kanorio 不会跟随 | 网址回传了 301、302、307 或 308 | 常见于网址少加/多加了结尾斜线 /、或网址被导向新域名。请将 Webhook 网址直接改成最终的 https:// 网址 |
| 接收端的 SSL 证书无效或已过期 | 接收端网址的 HTTPS 证书未正确安装、已过期或为自签证书 | 请更新接收端服务器的 SSL/TLS 证书(必须为公开受信任证书机构签发) |
| 查不到这个网址的域名 | DNS 解析不到该网址的域名 | 检查 Webhook 网址是否拼错字,并确认该域名的 DNS A/CNAME 记录已生效 |
| 无法连线到接收端 | 接收端服务器未启动,或防火墙挡下了连线 | 确认服务器正在运行,且防火墙已放行下方列出的 Kanorio 两个固定来源 IP |
| 接收端拒绝了这个请求(HTTP 401 / 403) | 接收端的身份验证或验签未通过 | 若接自建服务器,请确认接收端的签名密钥与 Kanorio 面板上的密钥一致,且验签时使用的是原始请求内容(Raw Body) |
| 接收端找不到这个网址(HTTP 404) | 网址路径不存在,或 Zapier/Make 的流程尚未开启 | 检查网址是否填错;若使用 n8n 的 Test URL 或 Make,确认已在对方界面开启监听或正式启用流程 |
| 接收端暂时限制了请求次数(HTTP 429) | 接收端(或 Zapier/Make 免费额度)达到频率上限 | 系统会自动排程重试;若频繁发生,请检查接收端工具的计划额度或放宽限流 |
| 接收端发生错误(HTTP 5xx) | 接收端服务器内部程序报错(如 500、502、503) | 请查看接收端服务器的错误日志(Error Logs),修复后在 Kanorio 点选「重送」 |
接收端有防火墙时(固定来源 IP 白名单)
Kanorio 的所有 Webhook 请求(包含首次推送、发送测试、手动重送与后台自动重试)皆固定从以下两个 IPv4 地址轮流发出。若您的公司服务器或防火墙设有来源白名单,请将两个 IP 都加入放行清单:
| 固定出口 IP(IPv4) |
|---|
137.184.250.60 |
167.99.28.231 |
安全提醒:IP 白名单仅作为网络层的额外防护,不能取代签名验证。自建接收端请务必一并验证
X-Kanorio-Signature。若未来我们需要新增或更换出口 IP,会提前在本页公告并保留新旧 IP 并行期。
与工程师交接(签名密钥与网站 ID)
如果您请内部或外包工程师开发接收程序,只需要在后台准备两项信息交给工程师,并附上Webhook 事件与签名验证这篇技术文档链接:
- 端点的「签名密钥(
whsec_...)」: 在「网站设置 › 开发者 › Webhooks」展开该端点,于「签名密钥」区块点击「显示」即可复制。- 怀疑密钥外流或定期更换时:点击「产生新密钥」。换发后,旧密钥在 24 小时内仍然有效(期间每则请求会同时附上新旧两把密钥算出的签名),让工程师有 24 小时可以零停机更新服务器设置;若在 24 小时内再按一次「产生新密钥」,上一把旧密钥就会立即作废。
- 网站 ID(
websiteId): 如果您的服务器同时接收多个 Kanorio 网站的 Webhook,可根据 JSON 内的websiteId字段分辨是哪个网站。您可以在后台「网站设置 › 一般」页面最底部直接复制该网站的websiteId。
网址、签名密钥与 7 天内的推送内容皆采用 Google Cloud 信封加密保存,且每次在面板显示密钥或查看内容都会留存审计记录(详见密钥与凭证如何保管)。
常见问题
不会受影响。Webhook 在免费版、专业版与商务版皆支持最多 10 个端点与事件细部过滤;变更或取消计划后,您设置的网址、显示名称、事件订阅与签名密钥都会照常运作。
当接收端响应超过 8 秒、网络瞬断,或有人在后台点击「重送」时,同一则通知就会再送一次。重试与重送都会带上完全相同的通知编号(Header 的 X-Kanorio-Delivery 与 JSON 的 id),请您的工程师或自动化流程用这个编号检查是否已处理过。
Kanorio 目前对外推送采用标准 JSON 格式的通用 Webhook。若要转发到 Slack、Discord、Telegram、Microsoft Teams 或 Google 表格,建议将 Webhook 先接到 Zapier、Make 或 n8n,再由它们排版并转发到您团队惯用的通讯工具。
您可以参考Webhook 事件与签名验证内每个事件的完整 JSON 范例;或先建立一个 Webhook 端点并点击「发送测试」,等真实网站发生一次事件(例如自己送出一笔测试表单)后,直接在后台「最近推送」点击「查看内容」,就能看到实际送出的完整 JSON。