Composio 与 HubSpot 集成实战OAuth 认证配置、故障排查与 Webhook 触发器完全指南【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio本指南以 Composio 开源仓库中的 HubSpot 支持文档为主体系统讲解如何在 Composio 上为 HubSpot 配置 OAuth 认证含 scope 规划与白标化、排查常见的连接与令牌交换故障、通过自定义工具调用 HubSpot API并为每个客户应用配置基于 Webhook 的触发器。读完本文你将掌握一套可直接落地的 HubSpot Composio 集成方案并能独立定位 400 令牌交换失败、授权循环、scope 缺失等高频问题。HubSpot 认证的两种模式Composio 托管应用与自定义 OAuth AppComposio 为 HubSpot 提供两种认证路径二者的取舍直接决定你的 scope 自由度、品牌呈现与配额归属参考 custom-app-vs-managed-app.mdxComposio 托管应用managed app由 Composio 统一注册并维护 HubSpot OAuth 应用开箱即用、最快上手。代价是用户在 OAuth 授权页看到的是 Composio 的品牌与默认 scope 集合且配额与其他用户共享。自定义 Auth Configcustomer-owned credentials使用你自己的 HubSpot OAuth 应用凭证Client ID / Client Secret创建自定义认证配置。适合白标化、需要额外 scope、需要独立配额或生产环境由团队自主掌控的场景。仓库中 HubSpot 的 toolkit slug 位于 ts/packages/cli/src/generated/toolkit-slugs.tshubspot在 SDK 与 CLI 中以hubspot标识该 toolkit。自定义 Auth Config 的核心字段从 custom-auth-hubspot.png 界面截图可以看到创建 HubSpot 自定义 Auth Config 时主要填写以下字段详见 custom-auth-configs.mdx字段说明Use your own developer credentials切换为使用你自己的 HubSpot 开发者应用凭证Client id你在 HubSpot Developer Portal 创建的 OAuth 应用的客户端 IDClient secret对应的客户端密钥必须与 HubSpot 应用当前值一致Base URL默认https://api.hubapi.com即 HubSpot API 请求的基础地址Redirect URI默认https://backend.composio.dev/api/v1/auth-apps/add需要添加到 HubSpot 应用的 OAuth 允许重定向列表Optional Scopes可选的 HubSpot API 权限范围以空格分隔Access TokenOAuth2 流程完成后由 Composio 自动注入无需手动填写创建完成后在代码中通过auth_config_id发起连接即可参考 custom-auth-configs.mdxconnection_request composio.connected_accounts.initiate( user_iduser_id, auth_config_idac_1234, ) connected_account connection_request.wait_for_connection() print(connected_account)const connReq await composio.connectedAccounts.initiate(userId, ac_1234); console.log(connReq.redirectUrl); const connection await composio.connectedAccounts.waitForConnection(connReq.id);配置 HubSpot OAuth Scopes 与品牌化HubSpot 对 scope 的处理比其他 OAuth 服务更严格配置前需要理解三条核心规则本文主体来自 toolkits-hubspot.md其详细版见 public.md。1. 按最小权限选择联系人 scope对于 HubSpot CRM 联系人最小必要 scope 是crm.objects.contacts.read与crm.objects.contacts.write。涉及敏感联系人字段时还需要对应的敏感 scope例如crm.objects.contacts.sensitive.read与crm.objects.contacts.sensitive.write。按业务实际所需选取避免一次授予过大权限。2. 用工具映射 scope而非靠猜在配置应用之前先用HubSpot 官方的 scope 文档与Composio 的 scopes/tools API将你要使用的工具/动作映射到所需的 scope 集合。这样可以得到精确的 scope 清单比凭经验猜测可靠得多。3. 保持 HubSpot 应用与 Composio Auth Config 的 scope 一致HubSpot 要求在 OAuth 之前scope 必须先声明在应用配置中连接时 HubSpot 不会动态调整 scope。因此配置在 Composio auth config 上的 scope 集合必须与 HubSpot 应用设置保持一致HubSpot 对required scopes非常严格配置在 HubSpot 应用上的必需 scope必须出现在 OAuth 请求/安装 URL 的scope参数中否则安装会失败optional scopes应通过 HubSpot 的optional_scope参数请求在 Composio 中对应的可编辑字段名为optional_scopes。如果选中的 HubSpot 账号/用户无法授予某个可选 scopeHubSpot 会直接省略它最终令牌中将不包含该 scope——所以不要假设可选 scope 已授予在依赖可选能力前先检查令牌/已授予的 scope。FAQ 文档 hubspot.md 给出了 Composio 与 HubSpot 开发者应用的 scope 分类匹配规则Composio 的scopes字段中的 scope必须在 HubSpot 中配置为Required必需或Conditionally required条件必需Composio 的optional_scopes字段中的 scope必须在 HubSpot 中配置为Optional可选不要在 Composio 中请求 HubSpot 开发者应用未启用的 scope。对应到 API 创建 Auth Config 的 credentials 结构{ credentials: { scopes: oauth crm.objects.contacts.read, optional_scopes: crm.objects.companies.read crm.objects.deals.read } }读取 Auth Config 时要同时检查credentials.scopes与credentials.optional_scopes两者共同代表 Composio 可为该配置请求的 HubSpot 权限。推荐的 scope 布局最小必需 可选扩展FAQ 推荐的自定义 HubSpot OAuth scope 方案是把必需清单保持最小oauth将工具相关的 HubSpot 权限放入optional_scopes并在 HubSpot 开发者应用中将同样的权限标记为可选。这样做的核心好处是灵活性HubSpot 要求 OAuth URL 中的 scope 分类与开发者应用中的分类一致如果日后把某个权限从可选改为必需所有使用该应用的 Auth Config 都必须同步通过scopes请求它否则新安装可能失败。把工具权限保持可选就能在不强制所有 Auth Config 联动的情况下逐步扩展权限。若某权限对产品功能是硬性要求则应保持必需并确保它在 HubSpot 中为 Required 且通过 Composioscopes发送。两种合法的配置示例源自 hubspot.md示例 A所有权限都在 HubSpot 中标记为必需{ credentials: { scopes: oauth crm.objects.contacts.read crm.objects.companies.read crm.objects.deals.read, optional_scopes: } }示例 B仅oauth为必需工具权限全部可选{ credentials: { scopes: oauth, optional_scopes: crm.objects.contacts.read crm.objects.contacts.write crm.objects.companies.read crm.objects.companies.write crm.objects.deals.read crm.objects.deals.write tickets timeline } }两种方式都有效关键是Composio 与 HubSpot 在哪些必需、哪些可选上达成一致。修改 scope 后需要重连受影响的 HubSpot 账号已存在的连接会保留原始授权时授予的 scope可选 scope 可以让连接在门户无法授予全部权限时依然成功但如果某个工具后续需要用户未授予的权限该工具仍可能报错。白标化客户可见的 OAuth 授权页若要为客户提供白标 OAuth 体验请使用客户自己的 HubSpot OAuth 应用凭证 / 自定义 Auth Config参考 white-labeling.mdx自行掌控授权页的品牌与同意consent呈现避免客户在 OAuth 页面上看到 Composio 托管应用的品牌托管应用在 HubSpot 审批通过前用户在连接时会看到Connecting an unverified app警告连接仍可工作但需要用户明确接受。如果该警告阻塞了上线使用自定义 Auth Config 即可掌控应用身份、审核状态与同意页见 hubspot.md。从 SDK 层面通过auth_configs.create传入自定义凭证即可参考 controlling-scopes.mdxauth_config composio.auth_configs.create( toolkithubspot, options{ type: use_custom_auth, auth_scheme: OAUTH2, name: HubSpot, credentials: { client_id: os.environ[HUBSPOT_CLIENT_ID], client_secret: os.environ[HUBSPOT_CLIENT_SECRET], scopes: oauth crm.objects.contacts.read, optional_scopes: crm.objects.companies.read crm.objects.deals.read, }, }, )const authConfig await composio.authConfigs.create(hubspot, { type: use_custom_auth, authScheme: OAUTH2, name: HubSpot, credentials: { client_id: process.env.HUBSPOT_CLIENT_ID!, client_secret: process.env.HUBSPOT_CLIENT_SECRET!, scopes: oauth crm.objects.contacts.read, optional_scopes: crm.objects.companies.read crm.objects.deals.read, }, });注意修改 scope 只影响新连接。已存在的连接保留用户此前授予的 scope若要向现有用户应用新 scope需要让其重新认证。排查 HubSpot OAuth 连接故障令牌交换 400先查 Client Secret再查 scope 对齐多个客户自有 HubSpot OAuth 故障案例表明令牌交换阶段返回 400 时第一优先级是核对 client secret详见 public.md从 HubSpot 应用复制当前正确的 client secret更新 Composio 自定义 Auth Config 使其一致如果 secret 曾被轮换或从错误的 HubSpot 应用复制了 secretHubSpot 会在令牌交换时返回 400。接着检查 scope 对齐。HubSpot 对必需 scope 极其严格配置在 HubSpot 应用上的必需 scope 必须出现在 OAuth 请求/安装 URL 的scope参数中安装才能成功如果 Composio Auth Config 请求的必需 scope 与客户自有 HubSpot 应用配置的必需 scope 不匹配授权/令牌交换都会失败可选 scope 通过 HubSpot 的optional_scope参数请求若账号无法授予则可能被省略令牌中不会包含它使用前务必检查实际授予的 scope。对于 Composio 托管的 HubSpot Auth Config不要修改默认 scope 集合。需要不同的必需/可选 scope 配置时应通过自定义 Composio Auth Config 使用自己的 HubSpot OAuth 应用。对于托管配置你只能移除托管应用上已存在的可选 scope无法添加新 scope也无法移除对托管配置非可选的 scope见 hubspot.md。授权循环检查 HubSpot 工作区与登录状态如果 HubSpot 流程在 Composio 侧正常工作的情况下反复循环请在正确的 HubSpot 工作区登录状态下重试并确认 OAuth 应用是 public 且配置正确。常见故障清单FAQ 汇总了以下高频排查项详见 hubspot.mdscope 不匹配或回调错误确认每个请求的 scope 都已在 HubSpot 启用且在 HubSpot 与 Composio 两侧的分类一致工具报缺失 scope在 Auth Config 与 HubSpot 开发者应用中补充该 scope然后重连账号联系人列表/搜索 limit 错误HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA与HUBSPOT_LIST_CONTACTS_PAGE单次请求的limit最大为 100Webhook 设置错误HubSpot webhook 要求public 应用并具备 App ID 与 Developer API Key私有/内部应用无法接收 webhook刷新或过期错误常见原因包括用户在 HubSpot 中撤销了应用授权、HubSpot 应用凭证变更、refresh token 失效或连接被用不同应用配置重新授权。轮换自定义 OAuth 凭证或修改 HubSpot 开发者应用后需要重连受影响的 HubSpot 账号。断开连接要断开 HubSpot删除对应的 connected account 即可。删除连接账号会断开 HubSpot 账号与 Composio 的关联并停止刷新该 access token。调用 HubSpot API 与 Toolkit 版本管理通过认证请求创建自定义 HubSpot 工具你可以创建一个自定义工具向 HubSpot API 端点发送已认证的请求——Composio 会为已连接的账号处理认证。如果需要也可以直接携带连接配置/自定义请求头调用 Provider。营销对象与 CRM 属性的差异对于 HubSpot 营销对象如 campaignsHubSpot不像 CRM 对象那样暴露 properties API。这类对象的字段可能需要直接在 HubSpot 门户中查看或配置无法通过常规属性接口读写。升级旧版 SDK 与 Toolkit 版本旧版本 HubSpot SDK/toolkit 使用双前缀 slug例如HUBSPOT_HUBSPOT_LIST_CONTACTS新版本改为单前缀例如HUBSPOT_LIST_CONTACTS。升级 SDK 后要显式使用最新的 HubSpot toolkit 版本否则可能引用到已废弃的 slug。此外HubSpot toolkit 的输出结构在近期迭代中发生过形态变化2025-12-10 起HubSpot与 Outlook、Notion 等共 57 个 toolkit的返回结果从通用的response_data对象升级为强类型字段若你的代码在latest版本下后处理旧的response_data结构需要适配新的扁平化、类型化响应见 changelog 12-10-252026-01-07 起工具执行错误统一返回包含status_code与message的标准结构HubSpot 也属于采用anyOf联合类型的 157 个 toolkit 之一字段接受null或多类型值时 schema 会完整保留见 changelog 01-07-26。为每个客户应用配置 HubSpot 触发器HubSpot 的 Webhook API 需要明确指定接收 Webhook 通知的 HubSpot 应用详见 toolkits-hubspot.md从 HubSpot 的 webhook 应用文档或开发者应用设置中获取App ID配置触发器时使用该 App ID对于使用客户自有 HubSpot 应用的触发器app_id与 developer API key 都是必需的——因为每个应用各自接收自己的 webhook 投递每个客户需要自己的 HubSpot 应用来完成 webhook 投递。这与 Composio 的自定义 OAuth Webhook 机制相衔接当触发类型带有requires_webhook_endpoint_setup标志时需要为你的 OAuth 应用注册 Composio 的 ingress URL形如https://backend.composio.dev/api/v3.1/webhook_ingress/{toolkit_slug}/{we_xxx}/trigger_event使事件能到达 Composio详见 custom-oauth-webhooks.mdx。同时牢记 HubSpot 侧的前提webhook 接收要求public 应用私有/内部应用无法接收 webhook。参考资料本文主体docs/kb/articles/toolkits-hubspot.md扩展版见 docs/kb/source/toolkits/hubspot/public.mdHubSpot 认证 FAQdocs/content/toolkits/faq/hubspot.md自定义认证配置docs/content/docs/auth-configuration/custom-auth-configs.mdx白标化docs/content/docs/auth-configuration/white-labeling.mdxScope 控制含 Python / TypeScript 示例docs/content/docs/authentication/controlling-scopes.mdx托管 vs 自定义认证docs/content/docs/authentication/custom-app-vs-managed-app.mdx自定义 OAuth Webhookdocs/content/docs/setting-up-triggers/custom-oauth-webhooks.mdxToolkit slug 定义ts/packages/cli/src/generated/toolkit-slugs.ts【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Composio 与 HubSpot 集成实战：OAuth 认证配置、故障排查与 Webhook 触发器完全指南
Composio 与 HubSpot 集成实战OAuth 认证配置、故障排查与 Webhook 触发器完全指南【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio本指南以 Composio 开源仓库中的 HubSpot 支持文档为主体系统讲解如何在 Composio 上为 HubSpot 配置 OAuth 认证含 scope 规划与白标化、排查常见的连接与令牌交换故障、通过自定义工具调用 HubSpot API并为每个客户应用配置基于 Webhook 的触发器。读完本文你将掌握一套可直接落地的 HubSpot Composio 集成方案并能独立定位 400 令牌交换失败、授权循环、scope 缺失等高频问题。HubSpot 认证的两种模式Composio 托管应用与自定义 OAuth AppComposio 为 HubSpot 提供两种认证路径二者的取舍直接决定你的 scope 自由度、品牌呈现与配额归属参考 custom-app-vs-managed-app.mdxComposio 托管应用managed app由 Composio 统一注册并维护 HubSpot OAuth 应用开箱即用、最快上手。代价是用户在 OAuth 授权页看到的是 Composio 的品牌与默认 scope 集合且配额与其他用户共享。自定义 Auth Configcustomer-owned credentials使用你自己的 HubSpot OAuth 应用凭证Client ID / Client Secret创建自定义认证配置。适合白标化、需要额外 scope、需要独立配额或生产环境由团队自主掌控的场景。仓库中 HubSpot 的 toolkit slug 位于 ts/packages/cli/src/generated/toolkit-slugs.tshubspot在 SDK 与 CLI 中以hubspot标识该 toolkit。自定义 Auth Config 的核心字段从 custom-auth-hubspot.png 界面截图可以看到创建 HubSpot 自定义 Auth Config 时主要填写以下字段详见 custom-auth-configs.mdx字段说明Use your own developer credentials切换为使用你自己的 HubSpot 开发者应用凭证Client id你在 HubSpot Developer Portal 创建的 OAuth 应用的客户端 IDClient secret对应的客户端密钥必须与 HubSpot 应用当前值一致Base URL默认https://api.hubapi.com即 HubSpot API 请求的基础地址Redirect URI默认https://backend.composio.dev/api/v1/auth-apps/add需要添加到 HubSpot 应用的 OAuth 允许重定向列表Optional Scopes可选的 HubSpot API 权限范围以空格分隔Access TokenOAuth2 流程完成后由 Composio 自动注入无需手动填写创建完成后在代码中通过auth_config_id发起连接即可参考 custom-auth-configs.mdxconnection_request composio.connected_accounts.initiate( user_iduser_id, auth_config_idac_1234, ) connected_account connection_request.wait_for_connection() print(connected_account)const connReq await composio.connectedAccounts.initiate(userId, ac_1234); console.log(connReq.redirectUrl); const connection await composio.connectedAccounts.waitForConnection(connReq.id);配置 HubSpot OAuth Scopes 与品牌化HubSpot 对 scope 的处理比其他 OAuth 服务更严格配置前需要理解三条核心规则本文主体来自 toolkits-hubspot.md其详细版见 public.md。1. 按最小权限选择联系人 scope对于 HubSpot CRM 联系人最小必要 scope 是crm.objects.contacts.read与crm.objects.contacts.write。涉及敏感联系人字段时还需要对应的敏感 scope例如crm.objects.contacts.sensitive.read与crm.objects.contacts.sensitive.write。按业务实际所需选取避免一次授予过大权限。2. 用工具映射 scope而非靠猜在配置应用之前先用HubSpot 官方的 scope 文档与Composio 的 scopes/tools API将你要使用的工具/动作映射到所需的 scope 集合。这样可以得到精确的 scope 清单比凭经验猜测可靠得多。3. 保持 HubSpot 应用与 Composio Auth Config 的 scope 一致HubSpot 要求在 OAuth 之前scope 必须先声明在应用配置中连接时 HubSpot 不会动态调整 scope。因此配置在 Composio auth config 上的 scope 集合必须与 HubSpot 应用设置保持一致HubSpot 对required scopes非常严格配置在 HubSpot 应用上的必需 scope必须出现在 OAuth 请求/安装 URL 的scope参数中否则安装会失败optional scopes应通过 HubSpot 的optional_scope参数请求在 Composio 中对应的可编辑字段名为optional_scopes。如果选中的 HubSpot 账号/用户无法授予某个可选 scopeHubSpot 会直接省略它最终令牌中将不包含该 scope——所以不要假设可选 scope 已授予在依赖可选能力前先检查令牌/已授予的 scope。FAQ 文档 hubspot.md 给出了 Composio 与 HubSpot 开发者应用的 scope 分类匹配规则Composio 的scopes字段中的 scope必须在 HubSpot 中配置为Required必需或Conditionally required条件必需Composio 的optional_scopes字段中的 scope必须在 HubSpot 中配置为Optional可选不要在 Composio 中请求 HubSpot 开发者应用未启用的 scope。对应到 API 创建 Auth Config 的 credentials 结构{ credentials: { scopes: oauth crm.objects.contacts.read, optional_scopes: crm.objects.companies.read crm.objects.deals.read } }读取 Auth Config 时要同时检查credentials.scopes与credentials.optional_scopes两者共同代表 Composio 可为该配置请求的 HubSpot 权限。推荐的 scope 布局最小必需 可选扩展FAQ 推荐的自定义 HubSpot OAuth scope 方案是把必需清单保持最小oauth将工具相关的 HubSpot 权限放入optional_scopes并在 HubSpot 开发者应用中将同样的权限标记为可选。这样做的核心好处是灵活性HubSpot 要求 OAuth URL 中的 scope 分类与开发者应用中的分类一致如果日后把某个权限从可选改为必需所有使用该应用的 Auth Config 都必须同步通过scopes请求它否则新安装可能失败。把工具权限保持可选就能在不强制所有 Auth Config 联动的情况下逐步扩展权限。若某权限对产品功能是硬性要求则应保持必需并确保它在 HubSpot 中为 Required 且通过 Composioscopes发送。两种合法的配置示例源自 hubspot.md示例 A所有权限都在 HubSpot 中标记为必需{ credentials: { scopes: oauth crm.objects.contacts.read crm.objects.companies.read crm.objects.deals.read, optional_scopes: } }示例 B仅oauth为必需工具权限全部可选{ credentials: { scopes: oauth, optional_scopes: crm.objects.contacts.read crm.objects.contacts.write crm.objects.companies.read crm.objects.companies.write crm.objects.deals.read crm.objects.deals.write tickets timeline } }两种方式都有效关键是Composio 与 HubSpot 在哪些必需、哪些可选上达成一致。修改 scope 后需要重连受影响的 HubSpot 账号已存在的连接会保留原始授权时授予的 scope可选 scope 可以让连接在门户无法授予全部权限时依然成功但如果某个工具后续需要用户未授予的权限该工具仍可能报错。白标化客户可见的 OAuth 授权页若要为客户提供白标 OAuth 体验请使用客户自己的 HubSpot OAuth 应用凭证 / 自定义 Auth Config参考 white-labeling.mdx自行掌控授权页的品牌与同意consent呈现避免客户在 OAuth 页面上看到 Composio 托管应用的品牌托管应用在 HubSpot 审批通过前用户在连接时会看到Connecting an unverified app警告连接仍可工作但需要用户明确接受。如果该警告阻塞了上线使用自定义 Auth Config 即可掌控应用身份、审核状态与同意页见 hubspot.md。从 SDK 层面通过auth_configs.create传入自定义凭证即可参考 controlling-scopes.mdxauth_config composio.auth_configs.create( toolkithubspot, options{ type: use_custom_auth, auth_scheme: OAUTH2, name: HubSpot, credentials: { client_id: os.environ[HUBSPOT_CLIENT_ID], client_secret: os.environ[HUBSPOT_CLIENT_SECRET], scopes: oauth crm.objects.contacts.read, optional_scopes: crm.objects.companies.read crm.objects.deals.read, }, }, )const authConfig await composio.authConfigs.create(hubspot, { type: use_custom_auth, authScheme: OAUTH2, name: HubSpot, credentials: { client_id: process.env.HUBSPOT_CLIENT_ID!, client_secret: process.env.HUBSPOT_CLIENT_SECRET!, scopes: oauth crm.objects.contacts.read, optional_scopes: crm.objects.companies.read crm.objects.deals.read, }, });注意修改 scope 只影响新连接。已存在的连接保留用户此前授予的 scope若要向现有用户应用新 scope需要让其重新认证。排查 HubSpot OAuth 连接故障令牌交换 400先查 Client Secret再查 scope 对齐多个客户自有 HubSpot OAuth 故障案例表明令牌交换阶段返回 400 时第一优先级是核对 client secret详见 public.md从 HubSpot 应用复制当前正确的 client secret更新 Composio 自定义 Auth Config 使其一致如果 secret 曾被轮换或从错误的 HubSpot 应用复制了 secretHubSpot 会在令牌交换时返回 400。接着检查 scope 对齐。HubSpot 对必需 scope 极其严格配置在 HubSpot 应用上的必需 scope 必须出现在 OAuth 请求/安装 URL 的scope参数中安装才能成功如果 Composio Auth Config 请求的必需 scope 与客户自有 HubSpot 应用配置的必需 scope 不匹配授权/令牌交换都会失败可选 scope 通过 HubSpot 的optional_scope参数请求若账号无法授予则可能被省略令牌中不会包含它使用前务必检查实际授予的 scope。对于 Composio 托管的 HubSpot Auth Config不要修改默认 scope 集合。需要不同的必需/可选 scope 配置时应通过自定义 Composio Auth Config 使用自己的 HubSpot OAuth 应用。对于托管配置你只能移除托管应用上已存在的可选 scope无法添加新 scope也无法移除对托管配置非可选的 scope见 hubspot.md。授权循环检查 HubSpot 工作区与登录状态如果 HubSpot 流程在 Composio 侧正常工作的情况下反复循环请在正确的 HubSpot 工作区登录状态下重试并确认 OAuth 应用是 public 且配置正确。常见故障清单FAQ 汇总了以下高频排查项详见 hubspot.mdscope 不匹配或回调错误确认每个请求的 scope 都已在 HubSpot 启用且在 HubSpot 与 Composio 两侧的分类一致工具报缺失 scope在 Auth Config 与 HubSpot 开发者应用中补充该 scope然后重连账号联系人列表/搜索 limit 错误HUBSPOT_SEARCH_CONTACTS_BY_CRITERIA与HUBSPOT_LIST_CONTACTS_PAGE单次请求的limit最大为 100Webhook 设置错误HubSpot webhook 要求public 应用并具备 App ID 与 Developer API Key私有/内部应用无法接收 webhook刷新或过期错误常见原因包括用户在 HubSpot 中撤销了应用授权、HubSpot 应用凭证变更、refresh token 失效或连接被用不同应用配置重新授权。轮换自定义 OAuth 凭证或修改 HubSpot 开发者应用后需要重连受影响的 HubSpot 账号。断开连接要断开 HubSpot删除对应的 connected account 即可。删除连接账号会断开 HubSpot 账号与 Composio 的关联并停止刷新该 access token。调用 HubSpot API 与 Toolkit 版本管理通过认证请求创建自定义 HubSpot 工具你可以创建一个自定义工具向 HubSpot API 端点发送已认证的请求——Composio 会为已连接的账号处理认证。如果需要也可以直接携带连接配置/自定义请求头调用 Provider。营销对象与 CRM 属性的差异对于 HubSpot 营销对象如 campaignsHubSpot不像 CRM 对象那样暴露 properties API。这类对象的字段可能需要直接在 HubSpot 门户中查看或配置无法通过常规属性接口读写。升级旧版 SDK 与 Toolkit 版本旧版本 HubSpot SDK/toolkit 使用双前缀 slug例如HUBSPOT_HUBSPOT_LIST_CONTACTS新版本改为单前缀例如HUBSPOT_LIST_CONTACTS。升级 SDK 后要显式使用最新的 HubSpot toolkit 版本否则可能引用到已废弃的 slug。此外HubSpot toolkit 的输出结构在近期迭代中发生过形态变化2025-12-10 起HubSpot与 Outlook、Notion 等共 57 个 toolkit的返回结果从通用的response_data对象升级为强类型字段若你的代码在latest版本下后处理旧的response_data结构需要适配新的扁平化、类型化响应见 changelog 12-10-252026-01-07 起工具执行错误统一返回包含status_code与message的标准结构HubSpot 也属于采用anyOf联合类型的 157 个 toolkit 之一字段接受null或多类型值时 schema 会完整保留见 changelog 01-07-26。为每个客户应用配置 HubSpot 触发器HubSpot 的 Webhook API 需要明确指定接收 Webhook 通知的 HubSpot 应用详见 toolkits-hubspot.md从 HubSpot 的 webhook 应用文档或开发者应用设置中获取App ID配置触发器时使用该 App ID对于使用客户自有 HubSpot 应用的触发器app_id与 developer API key 都是必需的——因为每个应用各自接收自己的 webhook 投递每个客户需要自己的 HubSpot 应用来完成 webhook 投递。这与 Composio 的自定义 OAuth Webhook 机制相衔接当触发类型带有requires_webhook_endpoint_setup标志时需要为你的 OAuth 应用注册 Composio 的 ingress URL形如https://backend.composio.dev/api/v3.1/webhook_ingress/{toolkit_slug}/{we_xxx}/trigger_event使事件能到达 Composio详见 custom-oauth-webhooks.mdx。同时牢记 HubSpot 侧的前提webhook 接收要求public 应用私有/内部应用无法接收 webhook。参考资料本文主体docs/kb/articles/toolkits-hubspot.md扩展版见 docs/kb/source/toolkits/hubspot/public.mdHubSpot 认证 FAQdocs/content/toolkits/faq/hubspot.md自定义认证配置docs/content/docs/auth-configuration/custom-auth-configs.mdx白标化docs/content/docs/auth-configuration/white-labeling.mdxScope 控制含 Python / TypeScript 示例docs/content/docs/authentication/controlling-scopes.mdx托管 vs 自定义认证docs/content/docs/authentication/custom-app-vs-managed-app.mdx自定义 OAuth Webhookdocs/content/docs/setting-up-triggers/custom-oauth-webhooks.mdxToolkit slug 定义ts/packages/cli/src/generated/toolkit-slugs.ts【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
