Workflow WebhooksWorkflow Webhooks

驗證

任何知道 Webhook URL 的人都能向其發送請求，因此驗證機制正是防止陌生人觸發您的 Shopify Flow 工作流程的關鍵。請在每個 Webhook 的「安全性」區段中進行設定。

這三種方法

方法 呼叫方如何證明其身分 何時使用它
無 沒有 僅供測試使用 - - 切勿用於生產環境
靜態代碼片段 請求標頭中的固定密鑰 幾乎所有整合功能（n8n、Make、Zapier、您自己的程式碼）
HMAC SHA-256 根據請求內容與共享密鑰計算出的簽名 發送方會對其 webhook（Stripe、GitHub、Slack 等）進行簽名

靜態代碼片段

按下 webhook 上的「產生」按鈕以取得一個強隨機代碼，或貼上您自己的代碼。呼叫方會將其包含在標頭中：

Webhook 編輯器：左側為名稱和驗證設定，右側為包含狀態、Webhook URL 及 Webhook ID 的「端點」卡片，上方則有「即時預覽」、「測試」和「使用情況」
靜態憑證：選擇發送者傳遞憑證的方式，產生或貼上憑證，並從「端點」卡片中複製 webhook URL。
bash
curl -X POST https://your-app-url/webhook/ab12cd34 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-token" \
  -d '{"orderId":"1001"}'

變更標題名稱

某些系統只能傳送其已使用的標頭。請在「進階設定」中設定 Auth 標頭名稱，我們便會從該標頭讀取憑證，而非從 X-Api-Key：

bash
  -H "X-Custom-Auth: your-token"

標頭名稱不區分大小寫。保留名稱將被拒絕 - - 例如：Host、Authorization、Cookie、X-Forwarded-*、X-Webhook-*、CF-* 以及類似名稱。這些標頭是由代理伺服器和內容傳遞網路（CDN）設定或重寫的，因此從其中讀取的標記將可能受攻擊者控制。

代幣的流向

並非每個發送者都能新增任意的標頭。**發送者該如何傳遞該憑證呢？**在「Webhook」分頁中提供了四個位置：

選擇 寄件者發送 何時使用它
在自訂頁首中 X-Api-Key: <token>，或您選擇的標頭名稱 預設設定，也是大多數整合方案的做法
作為一種持有人代幣 Authorization: Bearer <token> 該工具設有「持有人」或「API 憑證」欄位
以使用者名稱和密碼 HTTP Basic 驗證，由您自選使用者名稱，並將令牌設為密碼 此工具僅提供基本驗證
在網址中 ?token=<token>，或您選擇的參數名稱 發送者只能呼叫一個普通的 URL，且無法設定標頭

Authorization 特意保留了一個預留的_自訂_標頭名稱：Bearer 和 Basic 是其支援的使用方式，這兩者都會自動為您處理。針對這兩種方式發起的 401 請求，系統也會一併傳送 WWW-Authenticate 標頭，因為部分 HTTP 客戶端僅會在收到驗證請求後才會傳送憑證。

在四種選項中，「URL」選項的安全性最弱 - - URL 會出現在日誌、來源網址和瀏覽器瀏覽紀錄中 - - 因此請僅在發送者不給您其他選擇時才使用此選項。該應用程式會顯示包含憑證的完整 URL，並在儲存該請求的所有位置對該參數進行遮蔽。

HMAC SHA-256

發送方會使用共享密鑰對請求計算簽名；我們會重新計算該簽名並進行比對。洩露的請求無法透過篡改內容來重放，因為請求正文將不再與簽名相符。

服務供應商預設值

在「簽名服務提供者」下選擇您的發件者，我們將依照該提供者的精確方案進行驗證 - - 包括標頭名稱、編碼方式、簽名內容以及簽名有效期限。將其控制台上的簽名密鑰貼上即可完成設定。

共有 22 個內建服務提供商，每個都有專屬的設定指南：Calendly、Customer.io、GitHub、Lemon Squeezy、Linear、Mollie、Paddle、Paystack、Razorpay、Sanity、Sendcloud、Sentry、Shopify、 Slack、Square、標準 Webhooks（OpenAI、Supabase）、Stripe、Svix（Clerk、Resend）、Typeform、Vercel、WooCommerce 以及 Zendesk。若您使用的服務未列於此，請說明其採用自訂方案進行簽名的具體方式。

請參閱 驗證已簽名的 Webhook 以查看完整清單、自訂選項以及內建的簽名測試工具。

一個採用 HMAC 驗證且以 Stripe 作為簽名提供者的 Webhook，其中說明了「簽名密鑰」欄位、其驗證內容，以及「連接 Stripe」的步驟
已簽名的發送方（此處為 Stripe）：選擇服務供應商、貼上其簽名密鑰，編輯器便會顯示已勾選的項目以及如何進行連線。

通用 HMAC

由於沒有預設值，也沒有自訂方案，我們採用自己的方法：呼叫方傳送 X-Signature，即使用簽名密鑰對 X-Webhook-* 標頭值進行 HMAC-SHA256 運算所得的結果。

bash
curl -X POST https://your-app-url/webhook/ab12cd34 \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Data: value1value2" \
  -H "X-Signature: <hmac-sha256 of the X-Webhook-* values>" \
  -d '{"data":"payload"}'

拒絕是什麼樣子

驗證失敗時會傳回 401，其 JSON 內容會說明原因 - - 完整代碼清單請參閱 歷史與故障排除。在您編輯 webhook 期間，遭拒的呼叫仍會顯示在「即時請求檢視器」中，因此您可以確切了解呼叫被拒的原因。

在不造成停機的情況下輪替密鑰

若僅透過單一步驟變更密鑰，則所有使用舊密鑰簽署的請求都將失敗，直到發送方完成更新為止。透過 webhook 輪替密鑰可避免此情況：它會保留第二組有效的密鑰，該密鑰將與主要密鑰並行接受，適用於靜態憑證及所有簽名機制。

  1. 將新的密鑰輸入「**第二個有效密鑰」**欄位，然後儲存。現在這兩個密鑰均可被接受。
  2. 將發件者切換至新的密鑰。
  3. 按下「推廣」按鈕，系統會將其移至主欄位並清除次欄位，然後儲存。

任何請求在任何階段都不會被拒絕。第二個密鑰的儲存方式與主密鑰完全相同，且 API 絕不會回傳該密鑰本身 - - 僅會回傳是否已設定該密鑰的資訊。

妥善守住這個秘密

  • 無論在何種存取層級，我們的 REST API 或 MCP 伺服器都絕不會返回該憑證 - - 它們 僅回報是否已設定。請參閱 開發者 API 與 MCP。
  • 其儲存狀態下已進行加密。
  • 旋轉後會立即生效，因此請使用上方的「第二秘技」流程，而非 覆寫主欄位。
  • 儲存的呼叫歷史紀錄會遮蔽授權標頭、基本憑證以及 URL 憑證， 因此，瀏覽紀錄的截圖並不會洩露您的秘密。

進一步縮小範圍

驗證可證明呼叫者知曉密鑰。IP 白名單 會限制呼叫的來源，並可與上述任何模式結合使用。