如何在 HubSpot 的「以聯絡人為基礎的工作流程」中觸發 Webhook

在以聯絡人為基礎的工作流程中使用 Webhook，可在 HubSpot 與您的外部工具之間傳送或擷取資料。這讓您能夠跨不同平台自動化流程。您可以使用 POST Webhook 從 HubSpot 傳送資料，並使用 GET Webhook 從外部工具擷取資料。

在設定 POST 或 GET Webhook 時，可透過速率限制來控制 Webhook 的執行速度，並在 HubSpot 內或透過外部工具手動測試您的 Webhook 設定。 
您也可以了解如何驗證來自 HubSpot 的請求、如何使用 Webhook 自動啟動工作流程，以及如何在其他工作流程動作中使用 Webhook 回應資料。

請參閱開發人員 Webhook 文件，進一步了解 Webhook。如果您對在 HubSpot 中具體實作 Webhook 有任何疑問，請前往HubSpot 開發人員論壇發問。

Webhook 有哪些應用案例？

Webhook 的常見應用案例包括：

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

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

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

您可以透過工作流程傳送 POST 和 GET 請求。HubSpot 會將 webhook 流量與其他工作流程獨立管理，此舉旨在優化工作流程與 webhook 的效能。當 webhook 速度緩慢或發生超時時，工作流程動作的執行時間可能會比預期更長。

如何使用 POST webhook 從 HubSpot 傳送資料？

1. 在你的 HubSpot 帳戶中，點擊「更多」，然後前往「自動化」 > 「工作流程」。如果你的帳戶中沒有顯示「更多」，請直接前往「自動化」 > 「工作流程」。
2. 若要編輯現有工作流程，請點擊該工作流程的名稱。或者，建立一個新的工作流程。
3. 在工作流程編輯器中，點擊「+」加號圖示以新增動作。
4. 在左側面板的「資料操作」區段中，選取「傳送 Webhook」。
    

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

請注意：若要選取多個輸出項目，回應應以 JSON 物件的形式呈現。

如何使用 GET Webhook 將資料匯入 HubSpot？

1. 在你的 HubSpot 帳戶中，點擊「更多」，然後前往「自動化」 > 「工作流程」。如果你的帳戶中沒有顯示「更多」，請直接前往「自動化」 > 「工作流程」。
2. 若要編輯現有的工作流程，請點擊該工作流程的名稱。或者，建立一個新的工作流程。
3. 在工作流程編輯器中，點擊「+」加號圖示以新增一個動作。
4. 在左側面板的「資料操作」區段中，選取「傳送 webhook」。
    

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

9. 若要將 HubSpot 屬性用作查詢參數：
   • 在「查詢參數」區段中 ，輸入「鍵」，然後選取一個屬性。
   • 若要新增另一個屬性，請點擊「新增屬性」。
   • 若要移除屬性，請點擊delete 圖示。
10. 若要將靜態值用作查詢參數：
    • 在「查詢參數」區段中 ，輸入「鍵」，然後輸入一個值。
    • 若要新增另一個屬性，請按一下「新增靜態值」。
    • 若要移除一個屬性，請點擊delete 圖示。
11. 點擊「儲存」。

如何透過速率

限制

來控制 Webhook 的執行速度？

設定速率限制以決定 Webhook 動作應以何種速度執行。此速率限制亦會影響工作流程中隨後的所有動作。

1. 在你的 HubSpot 帳戶中，點擊「更多」，然後前往「自動化」 > 「工作流程」。如果你的帳戶中沒有顯示「更多」，請直接前往「自動化」 > 「工作流程」。
2. 點擊工作流程的名稱。
3. 在工作流程編輯器中，點擊「傳送 webhook」動作。
4. 在左側面板中，點擊「設定速率限制」以展開該區段。
5. 點擊以開啟「啟用速率限制」開關。預設情況下，此設定為關閉狀態。 
6. 設定您的速率限制： 
   • 動作執行次數：設定 每個時間區間內的最大執行次數。 
   • 時間範圍：設定速率限制的時間範圍。您可以以「秒」、「分鐘」或「小時」為單位設定此時間範圍。 

如何在 HubSpot 中測試我的 Webhook 設定？

在設定POST或GETWebhook 時，您可以執行測試以檢視 Webhook 的回應。測試期間，雖然會向第三方傳送及擷取資料，但 HubSpot 中的現有記錄將不受影響。若您使用 API 金鑰進行驗證，該 API 金鑰將不會顯示在任何測試請求中。

測試完 Webhook 後，您可以選擇要輸出的欄位，以便稍後在工作流程中作為輸入使用。請僅選擇每個回應中皆可用的輸出欄位。若某個輸出欄位在後續動作中被使用，但該欄位未出現在回應中，該動作將會失敗。

1. 在你的 HubSpot 帳戶中，點擊「更多」，然後前往「自動化」 > 「工作流程」。如果你的帳戶中沒有顯示「更多」，請直接前往「自動化」 > 「工作流程」。
2. 點擊工作流程的名稱。
3. 在工作流程編輯器中，點擊「傳送 Webhook」動作。
4. 在左側面板中，點擊「測試動作」以展開該區段。
5. 若您正在測試 POST 請求，Webhook 測試的設定方式將取決於您在 Webhook 動作中是否選擇了「自訂請求內容」或「包含所有 [object] 屬性」。
   • 若您已選取「自訂請求內容」，請輸入測試所需的屬性測試值。
   • 若您已選取「 包含所有 [object] 屬性」，請點擊[object]下拉式選單，然後選取要用於測試的記錄。
6. 點擊「測試」。
7. 若要檢查 webhook 詳細資訊，請選取「回應」或「請求」索引標籤。在每個索引標籤上，您可以點擊「展開全部」以展開所有區段，或點擊「收起全部」以收起所有區段。
   • 在「回應」標籤頁中，點擊「標頭：」或 「 正文：」以 展開各區段。
   • 在「請求」標籤頁中 ，請點擊「httpHeaders:」以 展開該區段。
     
     

如何使用外部工具測試 Webhook？

建立包含 Webhook 動作的工作流程後，您可以使用一個模擬的 Webhook URL 進行快速測試：

1. 在瀏覽器中瀏覽至https://webhook.site，並複製該唯一網址。
2. 在 Webhook 動作的「Webhook URL」欄位中，貼上該網址。
3. 工作流程啟用後，您可以手動註冊一個測試聯絡人。
4. 在外部測試 Webhook 時：
   • 若觸發了使用 POST 請求的 Webhook 動作，系統會將包含聯絡人所有資訊的 JSON 回應內容傳送至 Webhook，其中包含表單提交資料、清單成員資格以及所有聯絡人屬性值。接收系統隨後可解析該 JSON 資料，並將其應用於自身系統。
   • 若觸發的是使用 GET 請求的 Webhook 動作，系統將傳送一個通用 GET 請求，除非已套用額外的查詢參數。

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

如何驗證 webhook 請求是否來自 HubSpot？

當您在「觸發 webhook

動作的「驗證

區段中選取「請求簽名

時，HubSpot 會為 webhook 填入一個 X-HubSpot-Signature 標頭，其內容為您的應用程式 app-secret、HTTP 方法、URI 以及未解析的請求主體進行串接後，以 SHA-256 演算法計算出的雜湊值。 請參閱開發者文件以了解更多相關資訊。

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

• 擁有開發者帳戶。若您尚未擁有，請註冊開發者帳戶。
• 擁有一個應用程式。若您尚未擁有應用程式，請瞭解如何建立應用程式。
• 檢查簽名的雜湊值。

如何使用 Webhook 自動啟動工作流程？

Webhook 可用於觸發工作流程。當第三方應用程式中的資料發生變更時，即可觸發工作流程。進一步了解如何透過 Webhook 觸發工作流程。

如何在其他工作流程動作中使用 webhook 回應資料？

您帳戶所連接的 webhook 所提供的資料，可用於資料面板中的特定動作。

若要使用已連接 webhook 的資料：

1. 在你的 HubSpot 帳戶中，點擊「更多」，然後前往「自動化」 > 「工作流程」。如果你的帳戶中沒有顯示「更多」，請直接前往「自動化」 > 「工作流程」。
2. 點擊您工作流程的名稱。
3. 點擊「+」加號圖示以新增動作。
4. 在左側面板中，選擇一個使用「資料面板」的動作 。
5. 在資料面板的「動作資料」下方，選取您的「傳送 webhook」動作。接著，您即可使用已連線 webhook 的屬性。
    

當 webhook 失敗時會發生什麼情況？

HubSpot 將從失敗後一分鐘開始，在長達三天的期間內重試失敗的 webhook。後續的失敗將以逐漸增加的間隔進行重試，每次重試之間的最大間隔為八小時。

工作流程在收到 4XX 系列回應狀態碼後將不會重新嘗試。惟 429 速率限制錯誤除外；工作流程在收到 429 回應後會自動重新嘗試，並會遵循（若存在）Retry-After 標頭的設定。Retry-After 以毫秒為單位記錄。有關特定錯誤碼的例外情況，請參閱HubSpot 的開發者文件。