Webhook 的作用
Webhook 订阅某个特定的商店事件。当该事件发生时，Storeep 会立即将事件数据发送到你指定的 URL（API 类型）或你指定的邮箱地址（电子邮件 类型）。Webhook 常用于订单跟踪集成、CRM 同步、广告平台转化以及自动通知。
要管理 Webhook，请前往 设置 → Webhook。你需要 设置 权限才能查看或更改 Webhook。
Webhook 限制
- 每个商店最多 20 个 Webhook。尝试添加第 21 个会返回错误“你已达到每个商店 20 个 Webhook 的上限”。
- 列表按最新优先显示 Webhook，每页 40 条分页。
创建 Webhook
点击 添加新 Webhook，填写下面的字段，然后点击 添加。
激活
默认勾选。勾选时，Webhook 在你保存的那一刻即生效，匹配的事件会被分发。取消勾选可将 Webhook 保存为不接收任何内容的禁用状态。你可以随时通过编辑 Webhook 来切换这一项。
名称
- 必填。最多 50 个字符。
- 显示在列表中的描述性标签，例如 Facebook CAPI 订单已创建。
类型
- API：Storeep 发送一个携带事件数据的 HTTP POST 请求到你的 URL。
- 电子邮件：Storeep 发送一封包含事件数据的邮件到你的地址。
事件
触发 Webhook 的商店事件。共有三个事件：
- 会话已创建：你的商店中创建了一个新的访客会话。
- 订单已创建：下达了一笔新订单。
- 订单已更新：现有订单的状态或数据发生变化。
重要提示：电子邮件 类型只会投递 订单已创建 和 订单已更新。如果你选择 电子邮件 配合 会话已创建，Webhook 会保存但永远不会发送任何内容。如果你需要会话事件，请使用 API 类型。
格式
只有一个选项，Json：负载以 JSON 文档形式发送。
URL（仅 API 类型）
- 当类型为 API 时必填。最多 500 个字符。
- 该字段会为你显示一个
https://前缀，因此只需输入主机和路径即可，例如api.example.com/events/order。如果你粘贴了完整的https://或http://地址，保存前前缀会被去掉。 - 动态占位符：用双大括号语法
{{field_name}}将事件数据中的任意字段注入到 URL 中。例如：example.com/postback?cid={{fbclid}}&payout={{order_total}}。值会经过 URL 编码，而字段缺失的占位符会解析为空值。这让你无需代理即可将转化数据直接发送到广告平台。 - 地址会在移除占位符之后进行验证，因此无效的 URL 会返回“你输入的网址不正确”。
邮箱地址（仅电子邮件类型）
- 当类型为 电子邮件 时必填。必须是有效地址，最多 127 个字符。
编辑 Webhook
点击任意一行打开编辑器。每个字段都可编辑。只有当保存的类型为 API 时 URL 字段才会预填，只有当保存的类型为 电子邮件 时邮箱字段才会预填。点击 保存 以应用。在 激活 未勾选的状态下保存会禁用该 Webhook 但不会删除它。
Webhook 列表的列
- 名称：标签及其创建日期。
- URL / 电子邮件：目标地址。
- 类型：API 或电子邮件。
- 事件：会话已创建、订单已创建或订单已更新。
- 格式：Json。
- 状态：已激活或已停用。
删除 Webhook
选择一行或多行并点击 删除 Webhook。删除是永久性的，并会停止该订阅未来的所有投递。
投递、重试和失败邮件
本节适用于 API Webhook。电子邮件 Webhook 是发后即忘：只发送一次，没有重试也没有失败跟踪。
重试行为
- 每个请求有 5 秒超时。如果目标返回 5xx 错误、429（限流）或无法访问（连接错误），该投递会被视为临时失败并重试。
- 首次投递失败后，Storeep 会以指数退避方式重试，最多 5 次：约 30 秒、60 秒、120 秒、240 秒，然后是 480 秒之后。最后一次重试之后，事件会被丢弃。
- 除 429 之外的 4xx 响应（例如 404 或 403）会被视为永久失败。Storeep 不会重试它，因为错误或拒绝的端点不会自行修复。
- 当同一事件上有多个 Webhook 时，重试只会重新发送给失败的那些。已经返回成功的端点会被跳过，因此你不会收到重复投递。
失败通知邮件
- Storeep 会按每个 Webhook 统计连续失败的投递。在 连续 5 次失败 之后，店主会收到一封标题为“需要采取行动：你的 Storeep Webhook 正在失败”的邮件，使用店主的语言，列出 Webhook 名称、目标地址、事件和最后的 HTTP 状态码。
- 每个失败连续段你只会收到一封邮件。在该 Webhook 恢复之前不会再发送更多邮件。
- 一旦某次投递再次成功，失败计数器会重置为零并重新武装通知，因此未来出现的中断连续段可以再次给你发邮件。
提示与陷阱
- 你可以为同一事件创建多个 Webhook，例如将 订单已创建 作为两个独立条目同时发送到 CRM 和广告平台。
- 如果你的端点需要认证，可以在 URL 查询字符串中放入令牌，既可以硬编码，也可以通过来自事件数据的
{{placeholder}}实现，或者在它前面加一个代理，在转发前添加认证。 - 会话已创建 会为每个唯一的访客会话触发，在繁忙的商店上量可能很大。只有当你的端点能够承受这种吞吐量时才订阅它，并且记住它只能配合 API 类型使用。