跳到主要内容

Webhook

Webhook 会在店铺里发生某件事的那一刻,向你指定的网址发送一条消息:下了订单、付款成功、有人预约。通过它,你可以把 PersonaCart 连接到 Zapier、Make、n8n、你自己的服务器,或任何能接收网络请求的工具。

在哪里找​

侧边栏 → 设置 → 开发者工具 → Webhook。页面有 端点(我们发送到的地址,以及每一个的运行状况)和 安全(你的服务器如何确认请求是真实的)。

PersonaCart 中的 Webhook 页面
Webhook。

添加端点​

  1. 点 新建端点。
  2. 输入 网址。它必须以 https 开头。指向 localhost 或私有网络的地址不被接受。
  3. 添加一段说明,方便你记住它是干什么用的。
  4. 选择它应该接收的 事件。你必须至少选一个。
  5. 点 创建端点。签名密钥 会显示一次。请复制并妥善保存;之后不会再显示。

在某个端点上点 发送测试,可以立即发送一个示例事件,看看你的服务器是否收到。

可以发送哪些事件​

事件按发生的事情分组。例如:

范围事件
订单已创建、已更新、已完成、已履行、已送达、已取消、已退款、有争议
付款成功、失败、已退款
预约已创建、已确认、已更新、已改期、已取消、已完成、缺席
客户和线索客户已创建或更新、线索已创建或转化、联系表单已提交、已订阅通讯
结账已开始、已完成、已放弃
订阅已创建、已续费、付款失败、已取消
商品已创建、已更新、已删除、库存不足、降价
课程报名已创建、课时已完成、课程已完成、已颁发证书
其他发票、评价、支持工单、心愿单变化、营销活动

端点表单会显示你店铺的确切列表。在 Starter 套餐上,会发送订单、付款、预约、客户和线索事件。其他事件会保存在端点上,标有 专业版,升级后就会开始发送,无需再次设置(见套餐、限额和包含内容)。

确认请求确实来自我们​

任何人都可以向你的网址发送请求,所以在处理之前请先核对。每个 Webhook 都用该端点的签名密钥签名,采用 Standard Webhooks 方法:

  1. 校验签名。 请求头 webhook-id、webhook-timestamp 和 webhook-signature 带有签名。你把密钥交给 Standard Webhooks 库,它会替你完成校验。如果签名不匹配,请忽略该请求。
  2. 拒绝过期的请求。 超过 5 分钟的任何请求都会被拒绝,这样复制来的请求不会在以后被重放。
  3. 每个事件只处理一次。 我们可能会再次发送同一个事件(重试)。保存每个 webhook-id,并跳过见过的。
  4. 使用 Zapier、Make 或 n8n? 编辑端点时,添加一个 额外请求头(名称和值)。它会随每个 Webhook 一起发送,其值加密保存,之后不会再显示。

我们不公布固定的发送 IP 地址,所以请不要依赖 IP 白名单。请校验签名。

轮换签名密钥​

点 轮换密钥 获取新的密钥。你可以选择旧密钥何时失效:24 小时后、1 小时后,或立即(如果泄露了就用这个)。这样你有时间更新你的服务器。

查看投递日志​

在某个端点上打开 查看投递,可以看到每一次尝试:时间、事件、状态(成功、失败、待处理、重试中)、响应和耗时。可以按状态、事件或日期筛选。重试 会再次发送一次失败的投递,重试所有失败项 会把所有失败的投递排队。日志在 Starter 上保留 3 天,Pro 上 7 天,Scale 上 30 天。

每个端点都会显示已发送、已送达和失败的数量、成功率和一个健康标签。

暂停、恢复和出问题的端点​

  • 暂停 会停止向某个端点发送,但不删除它。恢复 会重新开始。
  • 如果某个端点持续失败,或者它的服务器回复该地址已不存在(HTTP 410),我们会停止发送,并把它标为 已停用 — 持续失败。修复网址或你的服务器,然后点 重新启用。最近 72 小时内的事件会重新发送。
  • 如果你的套餐允许的端点数量少于你已有的,最新的几个会显示 因套餐暂停。不会删除任何东西。升级或移除另一个端点后,它们就会重新发送。

好了解的​

删除后无法撤销

删除端点会停止向它的所有投递,并且无法撤销。Webhook 还会把你店铺的数据发送给另一项服务,所以只添加你控制或信任的地址。

AI 工具只有在你批准后才能设置新的 Webhook。见连接 AI。

常见问题​

Webhook 需要 API 密钥吗?

不需要。我们把它们发送到你的服务器,每个端点都有自己的签名密钥。API 密钥只用于连接 PersonaCart 的 AI 工具和脚本。

我最多可以添加多少个端点?

付费套餐没有上限。你的套餐决定发送哪些事件,以及投递日志保留多久。

我弄丢了签名密钥。

它只显示一次。用“轮换密钥”获取一个新的。

为什么我的端点显示“已停用”?

它持续失败,所以我们停止了发送。修复你的服务器或网址,然后点“重新启用”;最近 72 小时的事件会重新发送。