Automatisch 接入 HubSpot完整 OAuth 连接配置实战指南【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch本篇技术指南以 Automatisch 官方文档 HubSpot 连接配置 为骨架结合仓库中 HubSpot 应用模块的真实源码OAuth 授权流程、凭据校验、Token 刷新与请求签名系统讲解如何在 Automatisch 中完成 HubSpot 开发者账号创建、应用注册、凭据填写与连接验证的全流程。读完本文你将能够独立完成 HubSpot 与 Automatisch 的 OAuth 2.0 连接配置并理解每个配置项在底层源码中的实际作用。一、连接前的准备工作在开始配置之前需要确认以下前提条件你拥有一个可登录的 Automatisch 实例无论是云端版本还是自托管部署且具备创建连接的权限你拥有或准备创建一个 HubSpot 开发者账号——若你的团队已经在使用 HubSpot 客户关系管理CRM系统这一步通常由管理员或开发者完成准备用于注册 OAuth 应用的公网可访问的 Automatisch 地址因为在配置过程中需要把 Automatisch 生成的回调地址填写到 HubSpot 侧。从源码定义来看HubSpot 在 Automatisch 中被注册为一个支持连接supportsConnections: true的 OAuth 应用其 API 基地址为https://api.hubapi.com定义位于 packages/backend/src/apps/hubspot/index.js。这意味着所有 HubSpot 相关的自动化流程都建立在「先建立连接、再执行动作」的模型之上。二、创建 HubSpot 开发者账号与应用步骤 19官方文档给出的前九个步骤是标准的 HubSpot 侧准备工作对应流程如下打开HubSpot Developer 页面点击Create a developer account创建开发者账号按钮点击Create App Developer account按钮进入开发者账号创建流程按页面要求填写表单登录你的开发者账号点击Manage apps管理应用按钮点击Create app创建应用按钮新建一个 API 应用在Public app name字段中填写你的 API 应用名称例如Automatisch Integration切换到Auth标签页。需要说明的是HubSpot 的开发者账号与日常使用的 CRM 业务账号相互独立开发者账号主要用于创建和管理 OAuth 应用、申请 API Scope。如果你已经拥有 HubSpot 业务账号依然需要单独创建开发者账号来获取应用凭据。三、配置 OAuth Redirect URL步骤 10切换到Auth标签页后最关键的一步是填写Redirect URL(s)回调地址这里必须填入 Automatisch 连接创建页面提供的OAuth Redirect URL。在 Automatisch 中当你进入 HubSpot 应用的连接创建页面时页面会展示三个必填字段其中第一个就是只读的 OAuth Redirect URL。该字段的真实值由源码模板生成{ key: oAuthRedirectUrl, label: OAuth Redirect URL, type: string, required: true, readOnly: true, value: {WEB_APP_URL}/app/hubspot/connections/add, description: When asked to input an OAuth callback or redirect URL in HubSpot OAuth, enter the URL above., clickToCopy: true, }字段定义位于 packages/backend/src/apps/hubspot/auth/index.js。其中{WEB_APP_URL}是 Automatisch 的运行时占位符实际部署时会被替换为你的 Web 应用地址。也就是说你的 Redirect URL 大致形态为https://你的-automatisch-地址/app/hubspot/connections/addclickToCopy: true表示该字段在界面上支持一键复制方便你直接粘贴到 HubSpot 的 Redirect URL(s) 输入框中避免手抄出错。从底层实现看这个回调地址会在 OAuth 授权 URL 生成与 Token 换取两个环节被反复使用生成授权 URL 时generate-auth-url.js会把oAuthRedirectUrlField.value作为redirect_uri参数拼进授权链接见 generate-auth-url.js用授权码换取 Access Token 时verify-credentials.js同样需要把redirect_uri与授权阶段完全一致地传入 Token 端点否则 HubSpot 会拒绝请求见 verify-credentials.js。因此务必保证 HubSpot 后台填写的 Redirect URL 与 Automatisch 页面展示的值逐字符一致。四、选择权限范围 Scopes步骤 1112在Scopes标签页中需要勾选希望授权给 Automatisch 的权限范围。虽然文档建议选择你想与 Automatisch 一起使用的范围但从当前仓库源码看Automatisch 内置的 HubSpot 应用默认申请了两个最小权限集const scopes [crm.objects.contacts.read, crm.objects.contacts.write];定义位于 packages/backend/src/apps/hubspot/common/scopes.js。这两个 scope 分别对应 CRM 联系人对象的读取与写入权限恰好覆盖了 Automatisch 内置的两个 HubSpot 动作创建联系人、更新联系人所需的能力。在 generate-auth-url.js 中这些 scope 会以空格分隔拼接进授权链接const searchParams new URLSearchParams({ client_id: $.auth.data.clientId, redirect_uri: callbackUrl, scope: scopes.join( ), });实际生成的授权地址为https://app.hubspot.com/oauth/authorize。在实际操作中你可以按需在 HubSpot 侧额外勾选其他权限例如日后想使用更多 HubSpot API但需要注意自动化流程实际可调用的能力以授权时授予的 scope 与 Automatisch 内置动作定义的并集为准。五、获取并填写 Client ID 与 Client Secret步骤 1318完成 Scope 选择后继续以下操作点击Create App创建应用按钮完成应用创建回到Auth标签页复制页面展示的Client ID和Client Secret值回到 Automatisch 的 HubSpot 连接创建页面将Client ID粘贴到对应的Client ID输入框中将Client Secret粘贴到对应的Client Secret输入框中点击 Automatisch 页面上的Submit提交按钮。在 Automatisch 侧的字段定义中clientId与clientSecret均为必填required: true、可编辑readOnly: false的字符串字段。Client Secret 属于敏感凭据建议妥善保管仅用于 OAuth 流程不要提交到版本库或分享给无关人员。提交后Automatisch 会立即执行凭据验证流程。从 verify-credentials.js 的实现可以看到它向 HubSpot Token 端点发起authorization_code授权码交换请求POST https://api.hubapi.com/oauth/v1/token grant_typeauthorization_code client_id你的Client ID client_secret你的Client Secret redirect_uriAutomatisch回调地址 code授权码验证成功后返回的access_token、refresh_token、expires_in会被保存到连接数据中随后还会调用/oauth/v1/access-tokens/{accessToken}拉取令牌详情并写入screenName、hubDomain、scopes、hubId、userId等元信息用于在界面上展示连接的账户归属与授权范围。该内部接口封装在 get-access-token-info.js 中。六、连接建立后的自动续期与校验机制连接创建成功并不意味着一劳永逸HubSpot 的 Access Token 默认有时效expires_in过期后需要刷新。Automatisch 在底层实现了完整的 Token 生命周期管理自动刷新当 Access Token 过期时refresh-token.js 会使用已保存的refresh_token向/oauth/v1/token发起grant_typerefresh_token请求换取新的access_token与expires_in并同步更新保存的refreshToken。刷新令牌本身在 HubSpot 侧通常有较长有效期从而保证连接可以持续使用有效性校验is-still-verified.js 在每次使用前会调用getAccessTokenInfo校验当前令牌是否仍然有效无效时触发刷新流程请求签名所有发往 HubSpot 的 API 请求都会经过 add-auth-header.js 统一注入Authorization: Bearer accessToken头该逻辑通过beforeRequest: [addAuthHeader]挂载在应用定义中见 index.js。这套机制对使用者是完全透明的你只需保证初始配置正确后续的令牌刷新与请求鉴权都由 Automatisch 自动完成。七、连接成功后的使用内置动作示例完成连接第 19 步之后你就可以在流程编辑器中把 HubSpot 作为动作应用使用了。当前仓库内置了两个动作定义见 actions/index.jsCreate contact创建联系人向POST /crm/v3/objects/contacts提交联系人属性支持公司名、邮箱、名、姓、电话、网站 URL、所有者 IDhubspotOwnerId等字段各字段均支持变量引用Update contact更新联系人更新已存在的联系人信息。以创建联系人为例核心实现位于 create-contact/index.js它从流程步骤参数中读取表单字段组装成 HubSpot 期望的属性对象后提交并将返回的联系人数据写入动作输出项$.setActionItem供后续流程步骤继续引用。例如在Webhook 收到新线索 → 创建 HubSpot 联系人的自动化场景中上一步的响应字段可以直接映射到这里的email、firstName等参数上。八、排错与注意事项根据上文对源码的分析以下问题在实践中较为常见现象可能原因处理建议提交连接时提示凭据验证失败Client ID / Client Secret 填写错误或应用尚未保存成功回到 HubSpotAuth标签页重新复制逐一核对后再次提交授权页面报 redirect_uri 不匹配HubSpot 后台填写的 Redirect URL 与 Automatisch 展示的值不一致重新将 Automatisch 页面展示的 OAuth Redirect URL含完整域名与路径粘贴到 HubSpot Redirect URL(s)流程执行时提示权限不足创建应用时未勾选crm.objects.contacts.*相关 scope在 HubSpotScopes标签页补齐相应权限并重新建立连接长时间未使用后连接失效Refresh Token 过期或应用被删除在 Automatisch 连接管理页删除旧连接并重新创建需要注意的是本文描述的是基于仓库当前源码默认 scope 为联系人读写、回调路径为/app/hubspot/connections/add的配置流程如果你使用的是更新或修改过的分支请以实际部署版本的字段提示为准。九、小结本文完整复现了官方文档的 19 步连接配置流程并对照 packages/backend/src/apps/hubspot/ 目录下的真实源码解释了 OAuth Redirect URL、Scope、Client ID/Secret 三个关键配置在授权 URL 生成、Token 换取、自动刷新与请求签名等底层环节中的实际作用。按照上述步骤操作你即可在 Automatisch 中安全、稳定地接入 HubSpot CRM并立即开始使用内置的联系人创建与更新动作搭建自动化流程。【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考