DOCS
首页物流提供商专用 Webhook

使用 webhook 监听事件

获取 Zonos 集成的实时事件通知。

Webhook 为 Zonos 提供了一种方式，在发生某些事件时主动通知您的外部系统。当订阅的事件发生时，Zonos 将向您指定的 webhook URL 发送 HTTP POST 请求。请求体将包含事件详情，允许您的系统以编程方式处理该事件。

Webhook 对于将 Zonos 与其他平台集成、触发自动化工作流以及实时跨系统保持数据同步很有用。例如，您可以使用 webhook 来：

  • 在 Zonos 中创建订单时更新您的订单管理系统
  • 当发货被取消时通知您的履行提供商
  • 记录国际订单的状态变化以供审计之用

Webhook 类型 

所有可用的 webhook 类型都包含在 WebhookType 枚举中。每个类型的示例载荷可在我们的事件类型指南中找到。

创建 webhook 

要通过 API 创建 webhook：

1mutation WebhookCreate($input: WebhookCreateInput!) {
2 webhookCreate(input: $input) {
3 id
4 url
5 type
6 status
7 secret
8 headers {
9 key
10 }
11 }
12}

重要： 创建 webhook 时请保存 secret 值 — 该值仅在此处返回一次，您需要用它来验证 webhook 签名。请参阅下方的验证 webhook 签名。

编辑 webhook 详情 

要通过 API 编辑现有 webhook：

1mutation WebhookUpdate($input: WebhookUpdateInput!) {
2 webhookUpdate(input: $input) {
3 id
4 url
5 type
6 status
7 }
8}

验证 webhook 签名 

Zonos 发送的每个 webhook 请求都包含一个 zonos-signature 标头，以便您确认该请求确实来自 Zonos，且负载在传输过程中未被篡改。

该标头的值格式为：

timestamp=<unix-timestamp-ms>,hmac=<base64-encoded-signature>
  • timestamp — 请求签名时的时间，以 Unix 纪元毫秒为单位。
  • hmac — 原始 JSON 请求体的 HMAC-SHA256 签名，使用您 webhook 的 secret 作为密钥计算并进行 Base64 编码。

验证请求的步骤：

  1. 从 zonos-signature 标头中解析出 timestamp 和 hmac 的值。
  2. 使用您创建 webhook 时收到的 secret，对原始的、未经解析的请求体计算您自己的 HMAC-SHA256 签名。
  3. 使用恒定时间比较将您计算出的签名与 hmac 值进行比较，如果不匹配则拒绝该请求。
  4. （可选）拒绝 timestamp 早于几分钟前的请求，以防止被截获的请求遭到重放。Zonos 本身不强制执行送达时间窗口，因此是否进行此项检查由您决定。
1const crypto = require('crypto');
2 
3function verifyZonosWebhook(rawBody, signatureHeader, secret) {
4 const [timestampPart, hmacPart] = signatureHeader.split(',');
5 const receivedHmac = hmacPart.split('=')[1];
6 
7 const expectedHmac = crypto
8 .createHmac('sha256', secret)
9 .update(rawBody)
10 .digest('base64');
11 
12 const receivedBuffer = Buffer.from(receivedHmac);
13 const expectedBuffer = Buffer.from(expectedHmac);
14 
15 if (receivedBuffer.length !== expectedBuffer.length) {
16 return false;
17 }
18 
19 return crypto.timingSafeEqual(receivedBuffer, expectedBuffer);
20}

注意： 如果您在 webhook 上配置了自定义标头，这些标头也会随 zonos-signature 一起逐字包含在每个请求中。

查看 webhook 日志 

要通过 API 查看 webhook 日志：

1query WebhookLogs(
2$first: Int
3$after: String
4$filter: WebhookLogsFilterInput
5) {
6 webhookLogs(first: $first, after: $after, filter: $filter) {
7 edges {
8 node {
9 id
10 type
11 url
12 createdAt
13 responseStatus
14 }
15 }
16 }
17}
GraphQL API ReferenceTypes, inputs, and operations used in this guide
INPUTS

WebhookCreateInput WebhookLogsFilterInput WebhookUpdateInput

MUTATIONS

webhookCreate webhookUpdate

这个页面有帮助吗？

获取支持·法律文件·© 2026 Zonos
在此页面：
  • 使用 webhook 监听事件
  • Webhook 类型
  • 创建 webhook
  • 编辑 webhook 详情
  • 验证 webhook 签名
  • 查看 webhook 日志