用 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 添加的端点收到的信封格式相同。
验证原始请求体上的签名并检查时间戳。
保存已验证的投递后,再返回 2xx 响应。
每个事件只应用一次,并通过状态查询恢复遗漏信息。
安全地接收事件
- 保留原始正文。使用 secret 和 X-Webhook-Timestamp 验证 X-Webhook-Signature,并执行自己设定的时间容差。重新构造正文可能改变已签名的字节。
- 记录 X-Webhook-Delivery-Id 以跟踪投递尝试;同一投递的每次重试都使用相同的值。先保存已验证的事件再返回 2xx;无法安全接收时,应让发送方重试。
- 每个事件 id 仅处理一次。去重记录应能在重启后保留,并与订单更新协调完成。同一事件 id 会到达订阅该事件的每个端点。
- 较慢的工作放在接收后完成。签名证明真实性,不证明到达顺序。用 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 约定 · 订单状态 · 超时恢复.



