如何將 Sanity 連接到 Shopify Flow
透過 HMAC 驗證的 webhook，將 Sanity 與 Shopify Flow 串接。包含逐步設定指南、觸發器標籤設定、備註、電子郵件或元資料欄位更新。
每當有符合您查詢條件的內容被建立、更新或刪除時，Sanity 便會發送一個由 GROQ 驅動的 webhook。Workflow Webhooks 會將該呼叫轉為 Shopify Flow 觸發器，讓您的商店能據此做出反應：為顧客加上標籤、新增訂單備註、發送內部電子郵件、更新元資料欄位 - - 凡是 Shopify Flow 能做到的，都能實現。
本指南闡述了整個流程 - - 由 Sanity 發送請求、Workflow Webhooks 接收並驗證，最後由 Shopify Flow 執行操作 - - 且每項請求都會驗證 Sanity 的 HMAC 簽名，因此唯有 Sanity 才能啟動您的工作流程。
您可以打造什麼
- 當對應的 CMS 條目發生變更時，更新「Shopify」元資料欄位，以確保前端網站能與之保持同步。
- 當著陸頁發布時，請透過電子郵件通知您的商品推廣團隊。
- 在內容發布後啟動快取預熱工作流程。
常見的觸發事件包括：文件發佈、文件更新、文件刪除。
開始之前
- Workflow Webhooks 已安裝在您的 Shopify 商店中。
- Shopify Flow 已安裝，此應用程式可從 Shopify App Store 免費下載。
- 一個在 Sanity 上具有建立 webhook 權限的帳戶。
步驟 1 - 在 Workflow Webhooks 建立 Webhook
- 開啟 Workflow Webhooks → Webhooks → 建立 Webhook，並為其命名一個您在 Shopify Flow 中能認出的名稱，例如
Sanity events。 - 在「驗證」下，選擇 HMAC。
- 在「簽名提供者」下，選擇**「Sanity**」。該應用程式會自動為您填入標頭、演算法、已簽署載荷及重播視窗 - - 無需進行其他設定。
- 目前請將「密鑰」欄位留空，然後點選「儲存」。複製頁面顯示的 Webhook URL。
有關其他驗證模式，請參閱 驗證；關於如何選擇哪些欄位會傳送至 Shopify Flow，請參閱 有效載荷映射與 Shopify Flow 變數。
步驟 2 - 在 Sanity 中新增端點
在 Sanity 中，開啟 API → Webhooks，使用您複製的 URL 建立一個由 GROQ 驅動的 Webhook，並設定密鑰。
如何找出您的 Sanity 簽名密鑰
在由 GROQ 驅動的 webhook 上設定了 The Secret。
Sanity 官方關於 webhook 簽名的文件 中，提供了您帳戶的具體說明文字與螢幕截圖。
將該密鑰貼入 Workflow Webhooks 中的 webhook**「Secret」**欄位，並儲存。從此之後，每則 Sanity 傳送的資料在抵達 Shopify Flow 之前，都會經過驗證。
此處檢查的內容
| 什麼 | 價值 |
|---|---|
| 簽名欄 | sanity-webhook-signature |
| 簽名的位置 | 在該標頭的v1值中，該值包含以逗號分隔的key=value對 |
| 簽署的內容為何 | {timestamp}.{body} |
| 簽名 | HMAC-SHA256，採用 base64url 編碼 |
| 時間戳記 | 簽名標頭中的 t 值，單位為 Unix 毫秒 |
| 重播保護 | 無 - 此寄件者未對時間戳記進行簽名，因此所有有效的簽名均維持有效 |
| 這個秘密 | 作為純文字使用。請完全依照發件人顯示的內容貼上 |
在簽名載荷中，{body} 是原始請求正文（逐位元組），而 {timestamp} 則是上方的時間戳記。
若請求未能通過上述任一項檢查，系統將以「401」狀態拒絕該請求，並將其記錄於 歷史與故障排除，且該請求絕不會啟動工作流程。
步驟 3 - 建立「Shopify Flow」工作流程
- 在 Shopify Flow 中，建立一個工作流程，並選擇「Workflow Webhooks」觸發器。
- 按下「記錄事件」，然後從 Sanity 發送一個測試事件（或使用 Workflow Webhooks 中的**「發送測試**」功能），讓 Shopify Flow 學習您的資料結構。
- 您擁有的每個 Webhook 都會觸發相同的 Shopify Flow 觸發器，因此請針對 Webhook ID 新增第一個條件，以確保此工作流程僅限於 Sanity。該 ID 會顯示在 Webhook 頁面中。
- 新增您的操作 - - 標記客戶、新增備註、發送內部電子郵件、更新元資料欄位。
步驟 4 - 進行端到端測試
在 Sanity 中觸發一個真實事件。在**「Workflow Webhooks」→「History」**中，您應能看到狀態為「Success」的呼叫記錄。若簽名不正確，您將看到狀態為「Failed」的記錄並附有原因說明；而 驗證已簽名的 Webhook 則說明了簽名測試工具，該工具會精確顯示哪個步驟失敗。
簽名不符
依此順序：密鑰（最常見的原因 - - 多餘的空格，或來自錯誤環境的密鑰）、發送者是否使用了不同端點的密鑰，以及在 Sanity 與應用程式之間是否有任何環節重寫了請求正文。簽名涵蓋原始位元組，因此會重新格式化 JSON 的代理伺服器會導致簽名失效。 Webhook 頁面上的簽名測試工具會顯示實際經過簽名的精確文字內容。
每次發送請求時都會收到 401 錯誤
請確認 webhook 的驗證方式已設定為 HMAC 且已選取 Sanity 提供者，密鑰欄位已填入，並且 Sanity 傳送至該 URL 的內容完全與應用程式顯示的一致，包括末尾的代碼。
「歷史」中沒有任何內容
該請求從未送達。請在 Sanity 中重新檢查 URL，並查看 Sanity 自身的傳送日誌，確認其收到的回應。若出現 404，表示 webhook 錯誤或已被刪除；若出現 429，則表示您已超出方案的呼叫限制 - - 請參閱 方案與使用方式。
工作流程針對錯誤的事件執行
您商店中的每個 Webhook 都會觸發相同的「Shopify Flow」觸發器。請在工作流程的第一步中，針對 Webhook ID 新增一個條件，或者縮小您從 Sanity 傳送的事件範圍。
相關
- 驗證已簽名的 Webhook - 我們所核實的每家服務供應商，以及如何描述未經我們核實的服務供應商。
- 有效載荷映射與 Shopify Flow 變數 - 從載荷中擷取正確的欄位，並將其存入
Shopify Flow中。 - 重複送達防護 - 當 Sanity 重新嘗試傳送時會發生什麼情況。
- 歷史與故障排除 - 每個請求的日誌，並附有重播功能。