如何將標準 Webhooks 連接到 Shopify Flow
「標準 Webhooks」是一項用於簽署 Webhooks 的開放式規範，目前已被 OpenAI、Supabase Auth Hooks 以及越來越多的服務所採用。 一個預設設定即可涵蓋所有這些服務。Workflow Webhooks 會將該呼叫轉化為 Shopify Flow 觸發器，讓您的商店能對此做出反應：為客戶標記、新增訂單備註、發送內部電子郵件、更新元資料欄位 - - 任何 Shopify Flow 能做到的功能皆可實現。
本指南闡述了整個流程 - - Standard Webhooks 發送請求、Workflow Webhooks 接收並驗證，Shopify Flow 執行操作 - - 且每項請求都會驗證 Standard Webhooks 的 HMAC 簽名，因此唯有 Standard Webhooks 才能啟動您的工作流程。
您可以打造什麼
- 取用 OpenAI 的 webhook（例如已完成的批次工作或回應），並讓 Shopify Flow 根據該結果在您的商店中採取相應行動。
- 對 Supabase Auth Hook 做出反應，如此一來，當您自己的應用程式中有註冊操作時，便會為對應的 Shopify 客戶加上標籤。
- 無需設定自訂簽名，即可從任何遵循 standardwebhooks.com 規格的服務接收訊息。
常見的傳送事件：發送服務所定義的任何事件。
該預設設定亦會驗證來自 OpenAI 及 Supabase Auth Hooks 的 Webhook。
開始之前
- Workflow Webhooks 已安裝在您的 Shopify 商店中。
- Shopify Flow 已安裝，此應用程式可從 Shopify App Store 免費下載。
- 一個具備建立 Webhook 權限的 Standard Webhooks 帳戶。
步驟 1 - 在 Workflow Webhooks 建立 Webhook
- 開啟 Workflow Webhooks → Webhooks → 建立 Webhook，並為其取一個您在 Shopify Flow 中能認出的名稱，例如
Standard Webhooks events。 - 在「驗證」下，選擇 HMAC。
- 在「簽名提供者」下，選擇「標準 Webhooks」。應用程式會自動為您填入標頭、演算法、已簽名有效載荷及重播視窗 - - 無需進行其他設定。
- 目前請將「密鑰」欄位留空，然後點選**「儲存」**。複製頁面顯示的 webhook URL。
有關其他驗證模式，請參閱 驗證；關於如何選擇哪些欄位會傳送至 Shopify Flow，請參閱 有效載荷映射與 Shopify Flow 變數。
步驟 2 - 在「標準 Webhook」中新增端點
將該網址新增為發送服務中的端點，然後複製系統顯示的簽名密鑰（以 whsec_ 開頭）。
如何查找您的 Standard Webhooks 簽名密鑰
以 whsec_ 開頭的簽名密鑰。請將其完整貼上；若顯示為 v1,whsec_...（Supabase），請省略開頭的「v1,」。
Standard Webhooks 官方關於 webhook 簽名的文件 中，有您帳戶的具體說明文字與螢幕截圖。
將該密鑰貼入 Workflow Webhooks 中的 Webhook**「密鑰」**欄位，並儲存。從此之後，每則 Standard Webhooks 的傳送內容在送達 Shopify Flow 之前，都會經過驗證。
此處檢查的內容
| 什麼 | 價值 |
|---|---|
| 簽名標題 | webhook-signature |
| 簽名的位置 | 前綴 v1, 之後的標頭值 |
| 簽署的內容為何 | {header:webhook-id}.{timestamp}.{body} |
| 簽名 | HMAC-SHA256，base64 編碼 |
| 時間戳記 | webhook-timestamp 標頭，以 Unix 秒為單位 |
| 重播保護 | 簽名時間戳與當前時間相差超過 5 分鐘的請求將被拒絕 |
| 這個秘密 | 使用前需先進行 Base64 解碼。解碼前會先移除開頭的 whsec_。請完全按照發送者顯示的內容貼上 |
在已簽署的載荷中，{body} 代表原始請求正文（逐位元組），{timestamp} 代表上述的時間戳記，而 {header:webhook-id} 則是 webhook-id 的請求標頭。
若請求未能符合上述任一條件，系統將以「401」為由拒絕該請求，並將其記錄於 歷史與故障排除，且該請求絕不會啟動工作流程。
步驟 3 - 建立「Shopify Flow」工作流程
- 在 Shopify Flow 中，建立一個工作流程，並選擇「Workflow Webhooks」觸發器。
- 按下「記錄事件」，然後從「標準 Webhooks」發送一個測試事件（或使用「Workflow Webhooks」中的「發送測試」功能），讓 Shopify Flow 能學習您的資料結構。
- 您擁有的每個 Webhook 都會觸發相同的「Shopify Flow」觸發器，因此請針對 Webhook ID 新增第一個條件，以確保此工作流程僅限於「標準 Webhook」。該 ID 會顯示在 Webhook 頁面中。
- 新增您的操作 - - 標記客戶、新增備註、發送內部電子郵件、更新元資料欄位。
步驟 4 - 進行端到端測試
在「標準 Webhooks」中觸發一個真實事件。在 **Workflow Webhooks → 「歷史紀錄」**中，您應會看到狀態為「**成功」**的呼叫記錄。若簽名不正確，您將看到狀態為「失敗」的記錄並附有失敗原因；而 驗證已簽名的 Webhook 則說明了簽名測試工具，該工具會精確顯示哪個步驟失敗。
簽名不符▾
依此順序：密鑰（最常見的原因 - - 多餘的空格，或來自錯誤環境的密鑰）、發送者是否使用了其他端點的密鑰，以及在「標準 Webhook」與應用程式之間是否有任何環節重寫了正文。 簽名涵蓋原始位元組，因此若代理伺服器重新格式化 JSON，便會破壞簽名。Webhook 頁面上的簽名測試工具會顯示實際經過簽名的精確文字內容。
每次請求都會出現 401 錯誤▾
請確認 webhook 的驗證方式已設定為 HMAC，並已選取「標準 webhook」提供者；同時確認已填入密鑰，且「標準 webhook」發送至 URL 的內容完全與應用程式顯示的一致，包括末尾的代碼。
「歷史」中沒有任何記錄▾
該請求從未送達。請重新檢查「標準 Webhook」中的 URL，並查看「標準 Webhook」自身的傳送日誌，確認其收到的回應。若出現 404，表示 Webhook 錯誤或已被刪除；若出現 429，則表示您已超過方案的呼叫次數限制 - - 請參閱 方案與使用方式。
工作流程針對錯誤的事件執行▾
您商店中的每個 Webhook 都會觸發相同的「Shopify Flow」觸發器。請在工作流程的第一步中，針對 Webhook ID 新增一個條件，或從「標準 Webhook」中篩選您要傳送的事件。
請求失敗，錯誤訊息為「時間戳記超出容許範圍」▾
Standard Webhooks 會對時間戳記進行簽名，而應用程式會拒絕任何超過 5 分鐘的事件。這通常是發送端的時間同步問題，或是 Standard Webhooks 在很久之後才重新傳送該事件，並保留了原始的時間戳記。來自同一原始請求的重試事件無法通過驗證；請要求 Standard Webhooks 傳送一個新的事件。
相關
- 驗證已簽名的 Webhook - 我們如何審核每家服務供應商，以及如何描述未經我們審核的供應商。
- 有效載荷映射與 Shopify Flow 變數 - 從載荷中擷取正確的欄位，並將其存入
Shopify Flow中。 - 重複送達防護 - 當標準 Webhook 重試傳送時會發生什麼情況。
- 歷史與故障排除 - 每個請求的日誌，並附有重播功能。