Workflow WebhooksWorkflow Webhooks

如何將 Svix 連接到 Shopify Flow

Svix 是 Clerk、Resend、Superwall 以及許多其他產品背後所採用的 webhook 基礎架構。 若您的寄件者是透過 Svix 進行傳送，此預設設定將驗證此項資訊。Workflow Webhooks 會將該呼叫轉為 Shopify Flow 觸發事件，讓您的商店能據此做出反應：為客戶標記標籤、新增訂單備註、發送內部電子郵件、更新元資料欄位 - - 凡是 Shopify Flow 能執行的操作皆可。

本指南闡述了整個流程 - - 由 Svix 發送請求、Workflow Webhooks 接收並驗證，最後由 Shopify Flow 執行操作 - - 且每項請求都會驗證 Svix 的 HMAC 簽名，因此唯有 Svix 才能啟動您的工作流程。

您可以打造什麼

  • 當 Clerk 回報某位「Shopify」客戶已在您的應用程式中註冊或驗證電子郵件時，請為該客戶加上標籤。
  • 針對「重新寄送」或「退件」事件做出反應，並標記地址有問題的客戶。
  • 無需設定自訂簽名，即可接收來自任何搭載 Svix 技術的產品所傳送的訊息。

常見的傳送事件：發送服務所定義的任何事件。

該預設值同時也會驗證來自 Clerk、Resend 及 Superwall 的 Webhook。

開始之前

  • Workflow Webhooks 已安裝在您的 Shopify 商店中。
  • Shopify Flow 已安裝，此應用程式可從 Shopify App Store 免費下載。
  • 一個具備建立 Webhook 權限的 Svix 帳戶。

步驟 1 - 在 Workflow Webhooks 建立 Webhook

  1. 開啟 Workflow Webhooks → Webhooks → 建立 Webhook，並為其取一個您在 Shopify Flow 中能認出的名稱，例如 Svix events。
  2. 在「驗證」下，選擇 HMAC。
  3. 在「簽名提供者」下，選擇 Svix。該應用程式會自動為您填入標頭、演算法、已簽署的載荷以及重播視窗 - - 無需進行其他設定。
  4. 目前請將「密鑰」欄位留空，然後按下「儲存」。複製頁面顯示的 webhook URL。

有關其他驗證模式，請參閱 驗證；關於如何選擇哪些欄位會傳送至 Shopify Flow，請參閱 有效載荷映射與 Shopify Flow 變數。

步驟 2 - 在 Svix 中新增端點

將該 URL 作為端點新增至發送服務的 webhook 設定中，然後顯示並複製其簽名密鑰（以 whsec_ 開頭）。

如何找出您的 Svix 簽名密鑰

來自該服務 webhook 設定中，以 whsec_ 開頭的端點簽名密鑰。

Svix 官方關於 webhook 簽名的文件 中，有您帳戶的具體說明文字與螢幕截圖。

將該密鑰貼入 Workflow Webhooks 中的 webhook**「密鑰」**欄位，並儲存。從此之後，每封 Svix 郵件在傳送至 Shopify Flow 之前，都會經過驗證。

此處檢查的內容

什麼 價值
簽名標題 svix-signature
簽名的位置 前綴 v1, 之後的標頭值
簽署的內容為何 {header:svix-id}.{timestamp}.{body}
簽名 HMAC-SHA256，base64 編碼
時間戳記 svix-timestamp 標頭，以 Unix 秒為單位
重播保護 簽名時間戳與當前時間相差超過 5 分鐘的請求將被拒絕
這個秘密 使用前需先進行 Base64 解碼。解碼前會先移除開頭的 whsec_。請完全依照發送者顯示的內容貼上

在已簽署的載荷中，{body} 代表原始請求正文（按位元組對位元組），{timestamp} 代表上述的時間戳記，而 {header:svix-id} 則是 svix-id 的請求標頭。

若請求未能通過上述任一項檢查，系統將以「401」為由拒絕該請求，並將其記錄於 歷史與故障排除，且絕不會啟動工作流程。

步驟 3 - 建立「Shopify Flow」工作流程

  1. 在 Shopify Flow 中，建立一個工作流程，並選擇「Workflow Webhooks」觸發器。
  2. 按下「記錄事件」，然後從 Svix 發送一個測試事件（或使用 Workflow Webhooks 中的**「發送測試**」功能），讓 Shopify Flow 學習您的資料模式。
  3. 您擁有的每個 Webhook 都會觸發相同的「Shopify Flow」觸發器，因此請在 Webhook ID 上新增第一個條件，以確保此工作流程僅限於 Svix。該 ID 會顯示在 Webhook 頁面中。
  4. 新增您的操作 - - 標記客戶、新增備註、寄送內部電子郵件、更新元資料欄位。
Shopify Flow
在 Shopify Flow 中，選擇「選取觸發器」，開啟「Workflow Webhooks」，然後選擇「Webhook 觸發器」。
Shopify Flow 條件：Webhook ID 等於某個 Webhook 的 ID
每個工作流程的第一步：針對 webhook ID 設定一項條件，以便工作流程僅針對此 webhook 執行。
完成的工作流程：Webhook 觸發、以 Webhook ID 為條件，接著在「True」分支上發送內部電子郵件
完成的工作流程：觸發器、以 webhook ID 為條件，接著在「True」分支上執行您的動作。

步驟 4 - 進行端到端測試

在 Svix 中觸發一個真實事件。在**「Workflow Webhooks」→「History」中，您應能看到狀態為「Success」**的呼叫記錄。若簽名有誤，則會顯示一個失敗的記錄並附上原因；而 驗證已簽名的 Webhook 則說明了簽名測試工具，該工具會精確指出哪個步驟失敗。

「History」中開啟了一個呼叫，其中包含其請求標頭、有效載荷、狀態、持續時間及識別碼
「History」中的已傳送事件：狀態為「成功」表示 Shopify Flow 已接受該事件。
簽名不符▾

依此順序：密鑰（最常見的原因 - - 多餘的空格，或來自錯誤環境的密鑰）、發送者是否使用了不同端點的密鑰，以及 Svix 與應用程式之間是否有任何環節重寫了請求內容。簽名涵蓋原始位元組，因此會重新格式化 JSON 的代理伺服器會破壞簽名。 Webhook 頁面上的簽名測試工具會顯示實際被簽名的精確文字內容。

每次請求都會出現 401 錯誤▾

請確認 webhook 的驗證方式已設定為 HMAC 並選取 Svix 提供者，密鑰欄位已填入，且 Svix 傳送至 URL 的內容完全與應用程式所顯示的一致，包括末尾的代碼。

「歷史」中未顯示任何內容▾

該請求從未送達。請在 Svix 中重新檢查 URL，並查看 Svix 自身的傳送日誌，確認其收到的回應。若出現 404，表示 webhook 錯誤或已被刪除；若出現 429，則表示您已超過方案的呼叫次數限制 - - 請參閱 方案與使用方式。

工作流程針對錯誤的事件執行▾

您商店中的每個 Webhook 都會觸發相同的「Shopify Flow」觸發器。請在工作流程的第一步中，針對 Webhook ID 新增一個條件，或縮小您從 Svix 傳送的事件範圍。

請求失敗，錯誤訊息為「時間戳記超出容許範圍」▾

Svix 會簽署一個時間戳記，而應用程式會拒絕任何超過 5 分鐘的事件。這通常是發送端的時間同步問題，或是 Svix 在很久之後重新嘗試傳送時，仍沿用原始時間戳記所導致的狀況。來自同一原始請求的重試無法通過驗證；請要求 Svix 傳送新的事件。

相關