Webhooks

Webhooks 允许 Scrollengine 在事件发生时实时通知您的外部系统。使用 Webhooks 来构建自定义集成、自动化工作流程或与其他工具同步数据。

什么是 Webhooks

Webhook 是一个 HTTP POST 请求，当 Scrollengine 中发生特定事件时，会发送到您指定的 URL。您的服务器接收事件数据并可以据此采取操作。

可用的 Webhook 事件

事件	触发条件
order.created	创建新的配送订单
order.updated	订单详情或状态发生变化
order.delivered	订单被标记为已送达
order.cancelled	订单被取消
route.created	创建新的路线
route.started	配送员开始路线
route.completed	路线上的所有站点已完成
driver.assigned	配送员被分配到订单或路线

设置 Webhook

1. 前往 设置 > 集成 > Webhooks
2. 点击 添加 Webhook
3. 输入：
   • URL — 您服务器上接收 Webhook 的端点
   • 事件 — 选择要订阅的事件
   • 密钥 — 用于验证 Webhook 真实性的共享密钥
4. 点击 保存

Webhook 载荷

Webhooks 以 HTTP POST 请求的形式发送，包含 JSON 正文：

{
  "event": "order.delivered",
  "timestamp": "2026-03-13T14:30:00Z",
  "data": {
    "order_id": "12345",
    "shopify_order_id": "98765",
    "delivery_method": "local_delivery",
    "status": "delivered",
    "driver": {
      "id": "d-001",
      "name": "John Driver"
    }
  }
}

验证 Webhooks

每个 Webhook 都包含一个签名头用于验证：

1. Scrollengine 使用您的共享密钥对载荷进行签名
2. 签名包含在 X-Scrollengine-Signature 头中
3. 您的服务器应在处理之前验证签名

重试策略

如果您的端点返回非 2xx 状态码：

• Scrollengine 最多重试 3 次
• 重试使用指数退避策略（1 分钟、5 分钟、30 分钟）
• 3 次失败后，Webhook 将被标记为失败
• 您将收到通知以修复您的端点

使用场景

• 同步到 ERP — 将配送数据推送到您的库存或会计系统
• 自定义通知 — 触发短信、Slack 或其他警报
• 数据分析 — 将配送事件传输到您的分析平台
• 第三方物流 — 通知外部承运商或合作伙伴