Public Webhooks：把订单、出库、发票事件推给自己的系统

订阅 Docklify 事件——订单创建、订单履约、出库交运、发票生成、配送签收——以带签名的 HTTPS 推送实时发到您自己的接口，带测试事件、自动重试和投递日志。

Public Webhooks 把 Docklify 里发生的事变成发给您自己系统的消息。订单一创建、出库单一交给承运商、发票一生成，Docklify 就立刻往您指定的地址发一条 HTTPS 推送。典型用途：把订单同步进您自己的 ERP 或财务软件、用您自己的话术通知客户、给自己的看板喂数据、触发下游流程——不用再轮询 API。

可订阅的事件#

• order.created —— 销售订单创建时（手工录入、货主门户下单或 CRM 商机转单）。
• order.allocated —— 销售订单完成分配、库存已为该订单锁定。
• order.fulfilled —— 销售订单全部履约；带追踪号和承运商。
• order.cancelled —— 销售订单取消；带取消原因码。
• order.delivered —— 销售订单标记送达。
• shipment.fulfilled —— WMS 出库单交运（已交给承运商）；带追踪号。
• receipt.completed —— 入库单完成收货，全部明细行收完。
• inventory.adjusted —— 库位库存被直接调整（数量修正）。
• invoice.issued —— 应收发票生成。新发票为草稿状态，当前状态看 status 字段。
• delivery.completed —— 尾程配送单签收完成，已留签收凭证。
• test.ping —— 测试事件。随时可发，用来验证地址连通和验签是否正确。

创建订阅#

1. 打开 Integration → Webhooks，点「新建订阅」。
2. 名称：起个团队一看就懂的名字，比如“ERP 同步”。
3. 接收地址：您服务器上接收事件的 https 地址。必须用 https 且解析到公网地址——内网、局域网或回环地址会被拒绝。
4. 事件：勾选您想收的事件。以后随时可以改。
5. 保存后抄下签名密钥——以 whsec_ 开头。把它存进您服务器的配置里，验签时要用它确认推送确实来自 Docklify。以后在 Webhooks 页随时可以再次查看或轮换。

接收端要做的事#

每次投递都是一条带 JSON body 的 HTTPS 推送——信封。信封说明发生了什么（type）、什么时候（created_at），细节放在 data 里：

{
  "id": "<event id>",
  "type": "order.fulfilled",
  "created_at": "2026-10-20T12:00:00.000Z",
  "organization_id": "<your organization id>",
  "data": {
    "order_id": "<order id>",
    "order_no": "SO-1001",
    "status": "fulfilled",
    "tracking_number": "<tracking number>",
    "carrier_code": "ups"
  }
}

• 按 id 去重：投递是至少一次。自动重试和人工重发都复用同一个事件 id，所以把处理过的 id 记下来，重复的直接跳过。
• 回 2xx，而且要回得快：任何 2xx 都算成功。投递 10 秒超时，处理慢就先把事件存下来、立刻回 200，再慢慢处理。
• 其他情况一律算失败：返回非 2xx、返回重定向（3xx 不跟随跳转）、超时、地址不可达——都会触发下面说的自动重试。

验证签名#

任何知道您地址的人都能往上面发假事件，所以每条投递都带签名——信任数据之前先验签。完整规格（header 名、确切算法、Node 和 Python 各一行的示例）在 API 文档的 Webhooks 一节里。最关键的几点：

• 每条投递都带 header X-Docklify-Signature，形如 t=<unix 秒>,v1=<hex>。同一条投递还带 X-Docklify-Event（事件类型）和 X-Docklify-Delivery（投递 id）。
• v1 是用您的订阅签名密钥对字符串“<t>.<原文 body>”做 HMAC-SHA256 后得到的 hex。
• 永远用收到的原文 body 计算。绝不要先把 JSON 解析再重新序列化——空格和字段顺序一变，签名就对不上。
• 签名对不上，就不要处理这条事件。

发送测试事件#

1. 在 Integration → Webhooks 打开您的订阅，点「发送测试事件」。
2. Docklify 立刻往您的地址投递一条 test.ping。测试事件可以发给任何订阅，不要求订阅勾选过它（它本来就不在事件列表里）。
3. 去投递日志确认：那里有一条 delivered，加上您服务器上验签通过，就说明可以接真实事件了。

投递日志与失败排查#

每次投递都记在投递日志里（Integration → Webhooks → 投递日志）：事件类型、状态（pending / delivered / failed）、已尝试次数、最近一次的 HTTP 状态码和错误、下次重试时间。失败的投递会自动重试，间隔依次是 1 分钟、5 分钟、30 分钟、2 小时、6 小时——连同首次共 6 次尝试。最后一次仍失败就保持失败状态，直到您在日志里手动重发；重发复用同一个事件 id，您那边的去重会保证安全。

• 地址不可达：服务器挂了、地址写错了，或者域名解析不到公网地址。修好接收端，再从日志里重发。
• 证书问题：TLS 证书过期或自签名都会导致投递失败。用公共 CA 签发的有效证书。
• 返回非 2xx：接收端报错或拒绝了事件。看日志里的状态码和错误，修好原因，再重发。
• 超时：接收端处理超过 10 秒。先回 2xx，重活放到后台做。
• 您那边验签对不上：通常是 body 被重新序列化了，或者轮换密钥后还在用旧密钥——见上面「验证签名」。

暂停订阅与轮换密钥#

• 暂停：在 Webhooks 页把订阅设为已暂停。暂停期间 Docklify 不再向它投递新事件。随时可以恢复——维护接收端时，先暂停是最稳妥的做法。
• 轮换密钥：密钥可能泄漏、或知道密钥的同事离职时，在订阅页轮换。轮换后投递只用新密钥签名，所以要同时更新您服务器上的配置——还用旧密钥的接收端会拒绝新投递。