如何在 HubSpot 基於聯絡人的工作流程中觸發 Webhooks

在工作流程中使用 webhook，可在 HubSpot 與其他外部工具之間傳送或檢索資訊。webhook 具有多種應用場景，常見的實用案例包括：

• 當聯絡人於您的網站填寫特定表單時，將 HubSpot 聯絡人資料發佈至其他系統（例如 CRM）。

• 將交易資料傳送至外部物流處理系統以建立採購訂單。

• 從其他系統擷取資料以更新您的 HubSpot 記錄。

工作流程可發送 POST 與 GET 兩種請求。HubSpot 將 webhook 流量與其他工作流程獨立管理，此設計旨在優化工作流程與 webhook 效能。當 webhook 傳輸緩慢或超時，工作流程動作的執行時間可能超出預期。

請注意：HubSpot 會在 webhook 失敗後一分鐘開始，連續三天內重試失敗的 webhook。 後續失敗將以遞增間隔重試，每次嘗試間隔最長為八小時。收到 4XX 系列狀態碼回應後，工作流程將停止重試。
此規則的例外情況為 429 速率限制錯誤；收到 429 回應後，工作流程將自動重試，並遵循存在的 Retry-After 標頭。Retry-After 以毫秒為單位記錄。 請參閱HubSpot 開發人員文件了解特定錯誤代碼的例外處理。

欲深入瞭解 webhook，請參閱開發人員 webhook 文件。若對您在 HubSpot 中的 webhook 具體實作有疑問，請至HubSpot 開發人員論壇諮詢。

設定 POST 請求

1. 在你的 HubSpot 帳戶中，瀏覽「自動化」>「工作流程」。
2. 若要編輯現有工作流程，請點擊工作流程名稱。或建立新工作流程。
3. 在工作流程編輯器中，點擊+ 符號圖示新增動作。
4. 於左側面板的「資料操作」區段中，選擇「發送 webhook」。
    

5. 點擊「方法」下拉式選單並選擇「POST」。
6. 輸入webhook URL。
   • Webhook網址僅限使用安全通訊協定，且必須以HTTPS開頭。
   • 若需請求特定資訊，可於Webhook URL追加查詢參數，例如?queryparameter=abc 。
   • 若未添加查詢參數，系統將發送通用 POST 或 GET 請求。
7. 設定驗證類型以驗證發送至您的 webhook 之請求。您可選擇在 webhook 標頭中使用請求簽名，或採用 API 金鑰：
   • 若要在 webhook 標頭中使用請求簽名：
     • 點擊「驗證類型」下拉式選單，選擇「 在標頭中包含請求簽名」。
     • 接著輸入您的HubSpot 應用程式 ID。瞭解如何驗證請求簽名。
   • 若要使用 API 金鑰或透過開發者帳戶建立的公開應用程式進行驗證：
     • 使用 API 金鑰驗證時， API 金鑰名稱與位置取決於 webhook 的設定方式。基於安全性考量，API 金鑰不會顯示於任何測試請求中。使用 API 金鑰步驟：
       • 點擊「驗證類型」下拉式選單，然後選擇「 API 金鑰」。
       • 輸入您的API 金鑰名稱。
       • 點擊「API 金鑰位置」下拉式選單，選擇「查詢參數」或「請求標頭」。深入了解在 HubSpot 中使用API 金鑰的方法。
     • 若您正在向 HubSpot API 發送請求：
       • 點擊API 金鑰下拉式選單並選擇一組密鑰。該密鑰值必須採用Bearer [您的金鑰] 格式。
       • 將 API 金鑰名稱的值設定為Authorization。
       • 將API 金鑰位置 的值設定為 請求標頭。
8. 若要包含所有屬性，請選取「包含所有 [物件] 屬性」。
9. 若僅需包含特定屬性：
   • 請選擇「自訂請求本體」。
   • 若要使用 HubSpot 屬性自訂請求本體，請輸入「鍵值」並選擇屬性。欲新增其他屬性，請點擊「新增屬性」。
   • 若要使用靜態欄位自訂請求本體，請輸入「 鍵值」與「值」。欲新增其他屬性，請點擊「新增靜態值」。
   • 若要移除屬性或靜態值，請點擊刪除 垃圾桶圖示。
10. 點擊「儲存」。

請注意：若需選擇多個輸出欄位，回應內容應以 JSON 物件形式結構化呈現。

設定 GET 請求

1. 在你的 HubSpot 帳戶中，瀏覽「自動化」>「工作流程」。
2. 要編輯現有工作流程，請點擊工作流程名稱。或建立新工作流程。
3. 在工作流程編輯器中，點擊+ 符號圖示以新增動作。
4. 於左側面板的「資料操作」區段中，選擇「發送 webhook」。
    

5. 點擊「方法」下拉式選單並選擇「GET」。
6. 輸入webhook URL。
   • Webhook網址僅限使用安全通訊協定，且必須以HTTPS開頭。
   • 若需請求特定資訊，可於Webhook URL追加查詢參數，例如?queryparameter=abc 。
   • 若未添加查詢參數，系統將發送通用 POST 或 GET 請求。
7. 設定驗證類型以驗證發送至您的 webhook 之請求。您可選擇在 webhook 標頭中使用請求簽名，或採用 API 金鑰：
   • 若要在 webhook 標頭中使用請求簽名：
     • 點擊「驗證類型」下拉式選單，選擇「 在標頭中包含請求簽名」。
     • 接著輸入您的HubSpot 應用程式 ID。瞭解如何驗證請求簽名。
   • 若使用 API 金鑰或透過開發者帳戶建立的公開應用程式進行驗證：
     • 使用 API 金鑰驗證時， API 金鑰名稱與位置取決於 webhook 的設定方式。基於安全性考量，API 金鑰不會顯示於任何測試請求中。使用 API 金鑰步驟：
       • 點擊「驗證類型」下拉式選單，然後選擇「 API 金鑰」。
       • 輸入您的API 金鑰名稱。
       • 點擊「API 金鑰位置」下拉式選單，選擇「查詢參數」或「請求標頭」。深入了解在 HubSpot 中使用API 金鑰。
     • 若您正在向 HubSpot API 發送請求：
       • 點擊API 金鑰下拉式選單並選擇一組密鑰。該密鑰值必須採用Bearer [您的金鑰] 格式。
       • 將 API 金鑰名稱的值設定為Authorization。
       • 將API 金鑰位置 的值設定為 請求標頭。
8. 若您正在設定 GET 請求，可使用 HubSpot 屬性或將靜態值新增為查詢參數： 

9. 若要將 HubSpot 屬性用作查詢參數：
   • 在「查詢參數 」區段輸入 「鍵值」，然後選擇屬性。
   • 若要新增其他屬性，請點擊「新增屬性」。
   • 若要移除屬性，請點擊刪除 圖示。
10. 若要使用靜態值作為查詢參數：
    • 在「查詢參數」區段中 ，輸入「鍵值」，然後輸入對應的「值」。
    • 要新增另一項屬性，請點擊「新增靜態值」。
    • 若要移除屬性，請點擊刪除 圖示。
11. 點擊儲存。

為您的 webhook 設定速率限制

設定速率限制以決定 webhook 動作的執行頻率。此限制亦將影響工作流程中後續的所有動作。

1. 在你的 HubSpot 帳戶中，瀏覽「自動化」>「工作流程」。
2. 點擊工作流程名稱。
3. 在工作流程編輯器中，點擊「發送 webhook」動作。
4. 在左側面板中，點擊「設定速率限制」以展開該區段。
5. 點擊切換開關以啟用速率限制功能。此設定預設為關閉狀態。 
6. 設定速率限制： 
   • 操作執行次數：設定 每段時間內的最大執行次數。 
   • 時間範圍：設定速率限制的時間區間。可選擇以秒、分鐘或 小時為單位設定此時間範圍。 

在 HubSpot 內測試您的 webhook

設定POST或GETWebhook 時，可執行測試檢視 Webhook 回應。測試過程中雖會與第三方進行資料傳輸，但 HubSpot 現有記錄將不受影響。若使用 API 金鑰驗證，測試請求中將不會顯示該金鑰。

測試完成後，可選擇輸出欄位供後續工作流程輸入使用。請僅選取每則回應皆可取得的輸出欄位。若後續動作使用之輸出欄位未出現在回應中，該動作將執行失敗。

1. 在你的 HubSpot 帳戶中，瀏覽「自動化」>「工作流程」。
2. 點擊工作流程名稱。
3. 在工作流程編輯器中，點擊「發送 webhook」動作。
4. 於左側面板點擊「測試動作」以展開該區段。
5. 若測試 POST 請求，設定 webhook 測試的方式將取決於您是否選擇「自訂請求本體」或「在 webhook動作中包含所有 [object] 屬性」。
   • 若選擇自訂請求本體，請輸入測試所需的屬性測試值。
   • 若選擇 「包含所有 [物件] 屬性」，請點擊[物件]下拉式選單，然後選取要測試的記錄。
6. 點擊測試。
7. 要檢視 webhook 詳情，請選擇「回應」或「請求」分頁。在每個分頁中，您可點擊「展開全部」以展開所有區段，或點擊「收合全部」以收合所有區段。
   • 在「回應」標籤頁中，點擊headers: 或 body: 以 展開各區段。
   • 在「請求」標籤頁中 ，點擊「httpHeaders:」以 展開該區段。
     
     

外部測試您的 webhook

建立包含 webhook 動作的工作流程後，可透過測試用 webhook URL 進行快速驗證：

1. 於瀏覽器中前往https://webhook.site並複製該唯一網址。
2. 將該網址貼至工作流程中 webhook 動作的「Webhook URL」欄位。
3. 工作流程啟用後，即可手動註冊測試聯絡人。
   
   

4. 外部測試 webhook 時：
   • 若觸發使用 POST 請求的 Webhook 動作，系統將向 Webhook 發送包含聯絡人完整資訊的 JSON 回應主體，內容涵蓋表單提交紀錄、清單成員資格及所有聯絡人屬性值。接收端系統可解析此 JSON 資料並應用於自身程式。
   • 若觸發的是 GET 請求的 webhook 動作，系統將發送通用 GET 請求，除非已附加額外查詢參數。

請注意：歷史屬性值僅在聯絡人基礎工作流程中返回。其他類型工作流程使用的 webhook 僅會返回最新值。

驗證工作流程 webhook 中的請求簽名

當您在「觸發 webhook 動作」的「驗證」區段選擇「請求簽名」時，HubSpot 會為 webhook 填入 X-HubSpot-Signature 標頭，其內容為應用程式密鑰、HTTP 方法、URI 及未解析主體串接後的 SHA-256 雜湊值。詳細資訊請參閱開發人員文件。

驗證接收至您 URL 的請求是否來自 HubSpot：

• 您需擁有開發者帳戶。若尚未擁有，請註冊開發者帳戶。
• 擁有應用程式。若尚未建立應用程式，請參閱建立應用程式的說明。
• 檢查簽名雜湊值。

透過 webhook 觸發工作流程

webhook 可用於觸發工作流程。當第三方應用程式中的資料變更時，即可觸發工作流程。深入瞭解如何透過 webhook 觸發工作流程。

在資料面板中使用 webhook 資料

連結至您帳戶的 webhook 資料可用於資料面板中的特定操作。

使用已連結 webhook 的資料：

1. 在你的 HubSpot 帳戶中，瀏覽「自動化」>「工作流程」。
2. 點擊您的工作流程名稱。
3. 點擊+ 符號圖示新增動作。
4. 於左側面板選擇使用 資料面板 的操作項目 。
5. 於資料面板中，點擊「檢視屬性或動作輸出來源」下拉選單 ，選擇「Webhook 觸發器」。即可使用已連接 Webhook 的屬性。