如何在 HubSpot 基于联系人的工作流中触发 Webhooks

摘要

在基于联系人的工作流中使用Webhook，可在HubSpot与外部工具之间发送或获取数据。这使您能够跨不同平台自动化流程。可使用POST Webhook从HubSpot发送数据，使用GET Webhook从外部工具获取数据。

设置POST或GET webhook时，可通过速率限制控制webhook执行速度，并在HubSpot内或使用外部工具手动测试webhook配置。
您还可学习如何验证来自HubSpot的请求、如何使用webhook自动启动工作流，以及在其他工作流操作中使用webhook响应数据。 

在开发者webhook文档中深入了解webhook。若对HubSpot的具体webhook实施存在疑问，请访问HubSpot开发者论坛咨询。

webhook有哪些典型应用场景？

常见应用场景包括：

• 当访客在网站填写特定表单时，将 HubSpot 联系人数据推送至其他系统（如 CRM）。

• 将交易数据发送至外部物流系统以生成采购订单。

• 从其他系统获取数据以更新HubSpot记录。

工作流可同时发送POST和GET请求。HubSpot将webhook流量与其他工作流流程分开管理，以优化工作流和webhook性能。当webhook响应缓慢或超时时，工作流操作的执行时间可能超出预期。

如何使用POST webhook从HubSpot发送数据？

1. 在 HubSpot 帐户中，导航到自动化 > 工作流。
2. 要编辑现有工作流，请点击工作流名称。或创建新工作流。
3. 在工作流编辑器中，点击+号图标添加操作。
4. 在左侧面板的"数据操作"部分，选择"发送Webhook"。
    

5. 点击方法下拉菜单并选择POST。
6. 输入Webhook网址。
   • Webhook URL必须采用安全协议，且必须以HTTPS开头。
   • 若需请求特定信息，可在Webhook网址后添加查询参数，例如：?queryparameter=abc 。
   • 若未添加查询参数，系统将发送通用POST或GET请求。
7. 设置认证类型以验证发往Webhook的请求。可选择在Webhook头部使用请求签名，或使用API密钥：
   • 在 Webhook 头部使用请求签名：
     • 点击"身份验证类型"下拉菜单，选择" 在头部包含请求签名"。
     • 随后输入您的HubSpot应用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属性自定义请求正文，请输入键值并选择属性。添加其他属性请点击"添加属性"。
   • 若需使用静态字段自定义请求正文，请输入 键值对。添加其他属性请点击“添加静态值”。
   • 要删除属性或静态值，请点击删除 垃圾桶图标。
10. 在顶部点击保存。

请注意：若需选择多个输出项，响应应以 JSON 对象形式结构化。

如何使用GET webhook将数据导入HubSpot？

1. 在 HubSpot 帐户中，导航到自动化 > 工作流。
2. 要编辑现有工作流，请点击工作流名称。或创建新工作流。
3. 在工作流编辑器中，点击+ 号图标添加操作。
4. 在左侧面板的"数据操作"部分，选择"发送Webhook"。
    

5. 点击方法下拉菜单并选择GET。
6. 输入Webhook网址。
   • Webhook URL必须采用安全协议，且必须以HTTPS开头。
   • 若需获取特定信息，可在Webhook网址后添加查询参数，例如：?queryparameter=abc 。
   • 若未添加查询参数，系统将发送通用POST或GET请求。
7. 设置认证类型以验证发往Webhook的请求。可选择在Webhook头部使用请求签名，或使用API密钥：
   • 在 Webhook 头部使用请求签名：
     • 点击"身份验证类型"下拉菜单，选择" 在头部包含请求签名"。
     • 随后输入您的HubSpot应用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 属性作为查询参数：
   • 在“查询参数”部分 输入键值，然后选择属性。
   • 要添加其他属性，请点击“添加属性”。
   • 要删除属性，请点击删除图标。
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 操作中选择的"自定义请求正文"或"包含所有 [object] 属性"选项，测试设置方式将有所不同。
   • 若选择自定义请求正文，请输入测试所需的属性测试值。
   • 若选择 包含所有[对象]属性，请点击[对象]下拉菜单，然后选择要测试的记录。
6. 点击测试。
7. 要查看Webhook详细信息，请选择响应或请求选项卡。在每个选项卡中，您可以点击展开全部以展开所有部分，或点击折叠全部以折叠所有部分。
   • 在响应选项卡中，点击headers: 或 body: 以 展开相应部分。
   • 在请求选项卡 中，点击httpHeaders: 展开 该部分。
     
     

如何使用外部工具测试 webhook？

创建包含 webhook 操作的工作流后，可通过虚拟 webhook URL 进行快速测试：

1. 在浏览器中访问https://webhook.site并复制该唯一网址。
2. 在webhook操作的URL字段中粘贴该地址。
3. 工作流启用后，可手动添加测试联系人。
4. 外部测试webhook时：
   • 若触发POST请求的webhook操作，系统将向webhook发送包含联系人完整信息的JSON响应体，包括表单提交记录、列表成员资格及所有联系人属性值。接收系统可解析JSON数据并用于自身应用。
   • 若触发的是GET请求类型的Webhook操作，系统将发送通用GET请求（除非附加了额外查询参数）。

请注意：历史属性值仅在基于联系人的工作流中返回。其他类型工作流使用的webhook仅返回最新值。

如何验证webhook请求是否来自HubSpot？

当您在"触发webhook操作"的"身份验证"部分选择"请求签名"时，HubSpot会在webhook中添加X-HubSpot-Signature头部，其值为应用程序密钥、HTTP方法、URI及未解析正文的拼接结果经SHA-256哈希处理后的签名。 更多详情请参阅开发者文档。

验证接收到的请求是否来自 HubSpot：

• 拥有开发者账户。若尚未注册，请创建开发者账户。
• 拥有应用程序。若尚未创建应用程序，请了解如何创建应用程序。
• 检查签名的哈希值。

如何使用 webhook 自动启动工作流？

webhook 可用于触发工作流。当第三方应用中的数据发生变化时，即可触发工作流。了解如何通过 webhook 触发工作流。

如何在其他工作流操作中使用 webhook 响应数据？

账户关联的 webhook 数据可在数据面板的特定操作中使用。

使用关联 webhook 数据的方法：

1. 在 HubSpot 帐户中，导航到自动化 > 工作流。
2. 点击您的工作流名称。
3. 点击+ 号图标添加操作。
4. 在左侧面板中选择使用数据面板 的操作 。
5. 在数据面板的"操作数据"下，选择您的"发送 webhook"操作。此时即可使用关联 webhook 的属性。
    

Webhook失败时会发生什么？

HubSpot将在失败后1分钟开始重试，持续最多3天。后续失败将以递增间隔重试，每次尝试间隔最长为8小时。

收到4XX系列响应状态码后，工作流将停止重试。但429速率限制错误除外：收到429响应后工作流会自动重试，并遵循存在的Retry-After标头（该标头以毫秒为单位记录）。具体错误代码例外情况请参阅HubSpot开发者文档。