在 HubSpot 工作流程中使用 webhooks
上次更新時間: 四月 16, 2025
可搭配下列任何訂閱使用,除非另有註明:
|
在工作流程中使用 webhooks 在 HubSpot 與其他外部工具之間傳送或擷取資訊。webhooks 有多種用途,常用的 webhooks 用例包括:
-
當聯絡人在您的網站上填寫特定表單時,將 HubSpot 的聯絡人資料發佈到另一個系統,例如 CRM。
-
將交易資料傳送至外部出貨處理系統,以建立採購訂單。
- 從其他系統擷取資料,以更新您的 HubSpot 記錄。
您可以使用工作流程發送 POST 和 GET 請求。HubSpot 將 webhook 流量與其他工作流程分開管理。這樣做是為了簡化工作流程和 webhook 的效能。當 webhook 速度較慢或超時時,工作流程動作的執行時間可能會比預期長。
請注意:HubSpot 將重試失敗的 webhooks 長達三天,從失敗後一分鐘開始。隨後的失敗會以增加的間隔重試,每次重試之間最長相隔八小時。工作流程不會在收到 4XX 系列回應狀態代碼後重試。
此規則的一個例外是 429 速率限制錯誤;工作流程會在收到 429 回應後自動重試,並會尊重 Retry-After 標頭(如果存在)。Retry-After 以毫秒為單位記錄。在HubSpot 的開發人員文件中瞭解特定錯誤代碼例外情況。
在開發人員 webhooks 文件中瞭解有關webhooks 的更多資訊。如果您對 Webhooks 與 HubSpot 的具體實作有任何疑問,請聯絡HubSpot 開發人員論壇。
設定 POST 請求
- 在你的 HubSpot 帳戶中,瀏覽「自動化」>「工作流程」。
- 要編輯現有的工作流程,請點選工作流程的名稱。或建立新的工作流程。
- 在工作流程編輯器中,按一下+ 加號圖示以新增動作。
- 在左側面板的Data ops區段中,選擇Send a webhook。
- 按一下Method(方法)下拉式功能表,然後選擇POST。
- 輸入webhook URL。
- Webhook URL 受限於安全通訊協定,且必須以 HTTPS 開頭。
- 若要請求特定資訊,您可以在Webhook URL中加入查詢參數,例如
?queryparameter=abc
。 - 如果沒有新增查詢參數,則會傳送一般的 POST 或 GET 請求。
- 設定您的驗證類型,以驗證對 Webhook 的請求。您可以在 Webhook 標頭中使用請求簽章或使用 API 金鑰:
- 要在 webhook 標頭中使用請求簽章:
- 按一下驗證類型下拉式功能表。然後選擇 在標頭中包含請求簽章。
- 然後輸入您的HubSpot App ID。了解如何驗證請求簽章。
- 要在 webhook 標頭中使用請求簽章:
-
- 要使用 API 金鑰或透過開發人員帳戶建立的公共應用程式進行驗證:
-
-
- 使用 API 金鑰進行驗證時,所使用的API 金鑰名稱和API 金鑰位置取決於 webhook 的設定方式。基於安全理由,API 金鑰不會顯示在任何測試要求中。若要使用 API 金鑰,請
- 按一下驗證類型下拉式功能表。然後選擇 API 金鑰。
- 使用 API 金鑰進行驗證時,所使用的API 金鑰名稱和API 金鑰位置取決於 webhook 的設定方式。基於安全理由,API 金鑰不會顯示在任何測試要求中。若要使用 API 金鑰,請
-
-
-
-
- 輸入您的API 金鑰名稱。
- 按一下API 金鑰位置下拉式功能表。然後選擇查詢參數或請求頭。瞭解更多關於在 HubSpot 中使用API 金鑰的資訊。
- 如果您正在向HubSpot API的提出請求:
- 按一下API 金鑰下拉式功能表並選擇一個秘訣。秘密值的格式必須是Bearer [YOUR_TOKEN]。
- 將 API key name 的值設定為Authorization。
- 將API key location 的值設定為Request Header。
-
-
- 若要包含所有屬性,請選擇包含所有 [object] 屬性。
- 若要只包含特定屬性:
- 選擇自訂請求體。
- 若要使用 HubSpot 屬性自訂請求體,請輸入金鑰並選擇一個屬性。若要新增其他屬性,請按一下新增屬性。
- 若要使用靜態欄位自訂請求體,請輸入關鍵和值。若要新增其他屬性,請按一下新增靜態值。
-
- 若要移除屬性或靜態值,請按一下delete 垃圾桶圖示。
- 按一下儲存。
請注意:若要選擇多重輸出,回應的結構應為 JSON 物件。
設定 GET 請求
- 在你的 HubSpot 帳戶中,瀏覽「自動化」>「工作流程」。
- 若要編輯現有的工作流程,請按一下工作流程的名稱。或者,建立新的工作流程。
- 在工作流程編輯器中,按一下+ 加號圖示以新增動作。
- 在左側面板的Data ops區段中,選擇Send a webhook。
- 按一下Method(方法)下拉式功能表,然後選擇GET。
- 輸入webhook URL。
- Webhook URL 受限於安全通訊協定,且必須以 HTTPS 開頭。
- 若要請求特定資訊,您可以在Webhook URL中加入查詢參數,例如
?queryparameter=abc
。 - 如果沒有新增查詢參數,則會傳送一般的 POST 或 GET 請求。
- 設定您的驗證類型,以驗證對 Webhook 的請求。您可以在 Webhook 標頭中使用請求簽章或使用 API 金鑰:
- 要在 webhook 標頭中使用請求簽章:
- 按一下驗證類型下拉式功能表。然後選擇 在標頭中包含請求簽章。
- 然後輸入您的HubSpot App ID。了解如何驗證請求簽章。
- 要在 webhook 標頭中使用請求簽章:
-
- 要使用 API 金鑰或透過開發人員帳戶建立的公共應用程式進行驗證:
-
-
- 使用 API 金鑰進行驗證時,所使用的API 金鑰名稱和API 金鑰位置取決於 webhook 的設定方式。基於安全理由,API 金鑰不會顯示在任何測試要求中。若要使用 API 金鑰,請
- 按一下驗證類型下拉式功能表。然後選擇 API 金鑰。
- 使用 API 金鑰進行驗證時,所使用的API 金鑰名稱和API 金鑰位置取決於 webhook 的設定方式。基於安全理由,API 金鑰不會顯示在任何測試要求中。若要使用 API 金鑰,請
-
-
-
-
- 輸入您的API 金鑰名稱。
- 按一下API 金鑰位置下拉式功能表。然後選擇查詢參數或請求頭。瞭解更多關於在 HubSpot 中使用API 金鑰的資訊。
- 如果您正在向HubSpot API的提出請求:
- 按一下API 金鑰下拉式功能表並選擇一個秘訣。秘密值的格式必須是Bearer [YOUR_TOKEN]。
- 將 API key name 的值設定為Authorization。
- 將API key location 的值設定為Request Header。
-
-
- 使用 HubSpot 屬性作為查詢參數:
- 在查詢參數 部分,輸入Key,然後選擇一個屬性。
- 若要新增其他屬性,請按一下新增屬性。
- 若要移除屬性,請按一下delete 刪除圖示。
- 要使用靜態值作為查詢參數:
- 在查詢參數 部分下,輸入關鍵,然後輸入數值。
- 若要新增另一個屬性,請按一下新增靜態值。
- 若要移除屬性,請按一下delete 刪除圖示。
- 按一下儲存。
在 HubSpot 中測試您的 webhook
在設定POST或GETwebhook 時,您可以執行測試來檢視 webhook 的回應。在測試期間,當資料傳送至第三方並從第三方擷取時,HubSpot 中的現有記錄不會受到影響。如果你使用API key進行認證,API key將不會顯示在任何測試請求中。
測試 webhook 之後,您可以選擇要輸出哪些欄位,以便稍後在工作流程中作為輸入使用。僅選擇每次回應中都可用的輸出。如果輸出用於稍後的動作,但在回應中不可用,則動作會失敗。
- 在你的 HubSpot 帳戶中,瀏覽「自動化」>「工作流程」。
- 按一下工作流程的名稱。
- 在工作流程編輯器中,按一下傳送 webhook動作。
- 在左側面板中,按一下測試動作以展開該部分。
- 如果您要測試 POST 請求,根據您在 webhook 動作中是否選擇Customize request body(自訂請求正文) 或Include all [object] properties(包含所有 [object] 屬性) ,設定 webhook 測試將有所不同。
- 如果您選擇了自訂請求體,請輸入測試的屬性測試值。
- 如果您選擇 包含所有 [物件] 屬性,請按一下[物件]下拉式功能表,然後選擇要測試的記錄 。
- 按一下測試。
- 若要檢查 webhook 詳細資訊,請選擇 [回應]或[請求]標籤。在每個索引標籤上,您可以按一下全部開啟以展開所有區段,或按一下全部摺疊以摺疊所有區段。
- 在Response 索引標籤中,按一下headers: 或 body: 以展開每個部分。
- 在Request 索引 標籤中,按一下httpHeaders: 以展開區段。
從外部測試您的 webhook
使用 webhook 動作建立工作流程後,您可以使用假的 webhook URL 執行快速測試:
- 在瀏覽器中,瀏覽https://webhook.site 並複製唯一的 URL。
- 在 webhook 動作的Webhook URL欄位中,貼上 URL。
- 工作流程開啟後,您可以手動註冊一個測試連絡人。
- 在外部測試您的 Webhook 時:
- 如果觸發了具有 POST 請求的 webhook 動作,則會向 webhook 傳送 JSON 回應正文,其中包含聯絡人的所有資訊,包括表單提交、清單會員資格以及所有聯絡人屬性的值。接收系統可以解析 JSON 資料,並將其用於自己的應用程式。
- 如果觸發了具有 GET 請求的 webhook 動作,除非應用了額外的查詢參數,否則將會傳送一般的 GET 請求。
請注意:歷史屬性值只會在以聯絡人為基礎的工作流程中傳回。在所有其他工作流程類型中使用的 Webhook 只會傳回最近的值。
驗證工作流程 webhooks 中的請求簽章
如果您在觸發 webhook動作的驗證部分中選擇了請求簽章,HubSpot 會在 webhook 中填入 X-HubSpot-Signature 標頭,該標頭包含您應用程式的 app-secret、HTTP 方法、URI 和未解析正文的 SHA-256 切細值。請參閱開發者文件瞭解更多資訊。
驗證您的 URL 收到的請求是否來自 HubSpot:
從 webhooks 觸發工作流程
Webhooks 可用於觸發工作流程。當第三方應用程式中的資料變更時,即可觸發工作流程。進一步瞭解如何從 Webhooks 觸發工作流程。
在資料面板中使用 Webhook 資料
連接至您帳戶的 webhook 資料可用於資料面板中的特定動作。
- 在你的 HubSpot 帳戶中,瀏覽「自動化」>「工作流程」。
- 按一下工作流程的名稱。
- 按一下+ 加號圖示以新增動作。
- 在左側面板中,選擇使用資料面板的動作 。
- 在資料面板中,按一下從 下拉式功能表檢視屬性或動作輸出 ,然後選擇Webhook 觸發器。接著您就可以使用所連接 Webhook 的屬性。