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 的密鑰作為金鑰計算並經過 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 日誌