在 HubSpot 工作流程中使用 webhooks

在工作流程中使用 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。了解如何驗證請求簽章。

• • 要使用 API 金鑰或透過開發人員帳戶建立的公共應用程式進行驗證：

• • • 使用 API 金鑰進行驗證時，所使用的API 金鑰名稱和API 金鑰位置取決於 webhook 的設定方式。基於安全理由，API 金鑰不會顯示在任何測試要求中。若要使用 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。了解如何驗證請求簽章。

• • 要使用 API 金鑰或透過開發人員帳戶建立的公共應用程式進行驗證：

• • • 使用 API 金鑰進行驗證時，所使用的API 金鑰名稱和API 金鑰位置取決於 webhook 的設定方式。基於安全理由，API 金鑰不會顯示在任何測試要求中。若要使用 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 資料可用於資料面板中的特定動作。

若要使用所連接的webhook 的資料，請

• 在你的 HubSpot 帳戶中，瀏覽「自動化」>「工作流程」。
• 按一下工作流程的名稱。
• 按一下+ 加號圖示以新增動作。
• 在左側面板中，選擇使用資料面板的動作 。
• 在資料面板中，按一下從 下拉式功能表檢視屬性或動作輸出 ，然後選擇Webhook 觸發器。接著您就可以使用所連接 Webhook 的屬性。