DOCS
首頁為物流供應商而設 Webhook

透過 Webhook 聆聽事件

取得 Zonos 整合的即時事件通知。

Webhook 讓 Zonos 能夠在特定事件發生時，主動通知您的外部系統。當訂閱的事件發生時，Zonos 會向您指定的 Webhook URL 傳送 HTTP POST 請求。請求主體將包含事件詳細資訊，讓您的系統以程式設計方式處理該事件。

Webhook 適用於將 Zonos 與其他平台整合、觸發自動化工作流程，以及在即時系統中保持資料同步。例如，您可以使用 Webhook 來：

  • 在 Zonos 中建立訂單時更新訂單管理系統
  • 當貨運被取消時通知您的配送供應商
  • 記錄國際訂單的狀態變更以供稽核

Webhook 類型 

所有可用的 Webhook 類型都包含在 WebhookType 列舉中。每個類型的範例內容可以在我們的 Event Types 指南中找到。

建立 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 的密鑰作為金鑰計算後，以 Base64 編碼。

若要驗證請求：

  1. 從 zonos-signature 標頭中解析出 timestamp 和 hmac 值。
  2. 使用您在建立 Webhook 時收到的密鑰，對原始、未解析的請求主體計算您自己的 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 日誌