跳到主要内容
工程

Webhook 还是轮询?构建能够恢复遗漏的订单跟踪

用 NotPanel Webhook 接收变化,用状态轮询恢复遗漏。了解签名事件、重复投递、端点故障,以及安全更新订单的方法。

向收件箱发送信号的通知铃铛。

Sameer

Researcher

用 Webhook 接收日常变化,保留状态检查来确认本地记录与面板一致。如果还没有可靠的公共接收端,可以先使用批量轮询。

应用重启时订单可能已经完成;接收确认丢失后,同一事件也可能到达两次。订单跟踪需要处理这两种情况,避免显示旧信息或重复应用更新。

为每种方式分配明确任务

轮询:查询当前状态
action=status 返回查询时的状态,每次最多可合并 100 个订单 ID。间隔越短,请求越多,即使订单没有变化也一样。
Webhook:接收所选变化
NotPanel 将事件发送到已注册的 HTTPS 地址。这不占用客户端的 status 请求额度,但接收端仍需容量和监控。
核对:补全缺失信息
服务中断后或记录过旧时,查询相关订单。事件可能遗漏,重试次数有限,到达时间也没有保证。

NotPanel API 实际发送什么

在 dashboard 的 API 页面或通过 webhook.add 添加端点:填写公共 HTTPS URL,并选择所需事件,如 order.processing、order.in_progress、order.completed、order.partial、order.canceled、order.cancel_refused、refill.completed 和 refill.rejected;完整列表见 Webhook 参考文档。妥善保存 secret:它只显示一次,webhook.list 永远不会返回它。用 webhook.list 查看端点,用 webhook.test 发送测试 ping,用 webhook.remove 删除端点。

每次投递只携带一个事件,外面是一个简短的信封:id、type、schema_version、created_at、sequence 和 data。data.order 的字段与 action=status 的响应相同。下方简化示例只展示结构,并非真实订单。

{
  "id": "EXAMPLE_EVENT_ID",
  "type": "order.completed",
  "schema_version": 1,
  "created_at": "2026-10-10T12:30:00Z",
  "sequence": 1042,
  "data": {
    "order": {
      "order": 7001,
      "status": "Completed",
      "status_key": "completed",
      "remains": "0"
    }
  }
}

从已验证的正文读取事件类型。系统也会发送 X-Webhook-Event,但它不在签名范围内。在 dashboard 和通过 API 添加的端点收到的信封格式相同。

  1. 验证原始请求体上的签名并检查时间戳。

  2. 保存已验证的投递后,再返回 2xx 响应。

  3. 每个事件只应用一次,并通过状态查询恢复遗漏信息。

接收端设计示意图:可靠保存后确认,再处理事件,并用 status 补全遗漏。

安全地接收事件

  1. 保留原始正文。使用 secret 和 X-Webhook-Timestamp 验证 X-Webhook-Signature,并执行自己设定的时间容差。重新构造正文可能改变已签名的字节。
  2. 记录 X-Webhook-Delivery-Id 以跟踪投递尝试;同一投递的每次重试都使用相同的值。先保存已验证的事件再返回 2xx;无法安全接收时,应让发送方重试。
  3. 每个事件 id 仅处理一次。去重记录应能在重启后保留,并与订单更新协调完成。同一事件 id 会到达订阅该事件的每个端点。
  4. 较慢的工作放在接收后完成。签名证明真实性,不证明到达顺序。用 sequence 为事件排序;延迟事件若与较新状态冲突,应先查询 status,而不是直接覆盖。

阅读签名验证教程

接收端不可用时会发生什么

超时(10 秒)或非 2xx 响应都算一次失败尝试。NotPanel 在 24 小时内最多尝试 8 次:立即一次,然后在事件发生后 1 分钟、5 分钟、30 分钟、2 小时、6 小时、12 小时和 24 小时。连续失败 50 次,或 3 天内没有一次成功,端点会被暂停,并通知账户所有者。成功投递会清零失败计数。检查 webhook.list:没有收到通知,不代表没有变化。

定期核对未解决或过旧的订单,每批最多 100 个 ID,并遵守响应头与账户限额。修复接收端后,在 dashboard API 页面的 Webhook 区域恢复该端点,这会清零其失败计数。也可以用 webhook.remove 删除它,再用 webhook.add 重新添加修复后的 HTTPS URL 和所需事件,安全保存新的 secret 并更新接收端的签名验证。公开 API 没有恢复端点的操作。暂停时排队的投递不会重发,请用 status 核对遗漏的订单状态。

测试成功演示以外的情况

使用模拟消息和自己生成的测试 secret,无需客户真实订单。

  • 同一投递发送两次,应只产生一次更新。
  • 同一事件投递两次,中间重启接收端,仍应识别为已处理。
  • 修改一个字节或使用旧时间,应按自己的验证策略失败。
  • 发生中断并收到延迟事件后,status 应恢复当前订单视图。

选择需要的事件、验证 secret 并及时确认,也见于 GitHub 的 Webhook 建议. 本文的请求头、正文格式和重试限制遵循 NotPanel 的约定。

常见问题

可以只使用轮询吗?

可以。批量查询并按订单量及限额安排间隔。创建和跟踪订单并不强制要求 Webhook。

Webhook 会立即且只到达一次吗?

不会保证。投递可能延迟或重复。验证每次投递,每个事件仅处理一次,并保留状态核对作为恢复方式。

应该检查哪些请求头?

检查 X-Webhook-Signature 和 X-Webhook-Timestamp,再从已验证的正文读取 id、type 和 data。X-Webhook-Delivery-Id 仅用于跟踪投递尝试。

Webhook 能保护结果未知的 add 吗?

这是不同问题。重试 add 时保留原 request_id 和相同参数,然后保存找回的订单 ID。

参考资料: Webhook 约定 · 订单状态 · 超时恢复.

分享本文

作者:Sameer

Researcher