Kanorio

Webhook 设置与管理

约 6 分钟进阶

当您的网站上有事情发生时 - 例如买家完成支付、包裹出货或送达、访客提交联系表单、发件域名验证失效或流量突破里程碑 - 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。
  • 自建系统:由您的工程师提供一个可接收 POST JSON 请求的 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 天内的通知随时可点击「重送」再推送一次。手动重送会使用相同的通知编号(方便接收端去重),且如果重送失败,不会触发后台重试、也不会计入自动暂停的失败次数。

送不出去时的自动重试与自动暂停

当您的接收端没有正常响应时,系统会依响应状态自动处理:

  1. 自动退避重试(最多 8 次、约两天半): 如果接收端超过 8 秒没有响应、发生网络错误,或回传 HTTP 429(请求太频繁)、5xx(服务器错误),Kanorio 会在后台依序自动重试:1 分钟后 → 5 分钟后 → 30 分钟后 → 2 小时后 → 8 小时后 → 24 小时后 → 再 24 小时后,加上首次送出总共最多尝试 8 次。
  2. 不重试的错误(3xx 与其他 4xx): 如果接收端回传重定向(301、302 等)或设置错误(如 400、401、403、404),代表网址或验证设置有问题,系统不会重试,直接计为 1 次推送失败。
  3. 立即暂停(410 Gone): 如果接收端回传 410 Gone,代表对方明确宣告该网址已停用,系统会立即暂停这个端点。
  4. 连续 3 次失败自动暂停: 当某个端点连续 3 则通知最终都送不出去(例如重试 8 次用尽仍失败,或连续 3 次收到 404),系统会将该端点标为「连续失败,已暂停」,停止继续推送,并寄送平台通知与 Email 给具「管理串接服务」权限的成员(拥有者、管理员,以及勾选此权限的自定义角色)。
  5. 如何重新启用: 确认接收端(或 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 事件与签名验证这篇技术文档链接:

  1. 端点的「签名密钥(whsec_...)」: 在「网站设置 › 开发者 › Webhooks」展开该端点,于「签名密钥」区块点击「显示」即可复制。
    • 怀疑密钥外流或定期更换时:点击「产生新密钥」。换发后,旧密钥在 24 小时内仍然有效(期间每则请求会同时附上新旧两把密钥算出的签名),让工程师有 24 小时可以零停机更新服务器设置;若在 24 小时内再按一次「产生新密钥」,上一把旧密钥就会立即作废。
  2. 网站 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。