HubSpot 连接器
HubSpot 连接器
通过 Tajo 将你的 HubSpot CRM 连接到 Brevo,实现双向联系人同步、交易追踪、互动数据同步,以及跨两大平台的统一营销自动化。
概览
| 属性 | 值 |
|---|---|
| 平台 | HubSpot |
| 类别 | CRM |
| 部署复杂度 | 中等 |
| 官方集成 | 是 |
| 同步数据 | 联系人、公司、交易、工单、事件 |
| API Base URL | https://api.hubapi.com |
功能特性
- 双向联系人同步 - 实时在 HubSpot 与 Brevo 之间保持联系人同步
- 交易管道追踪 - 同步交易阶段和金额,用于基于收入的分群
- 公司数据同步 - 将联系人关联到公司记录及其企业画像数据
- 工单集成 - 追踪支持工单,用于客户健康度评分
- 互动追踪 - 同步邮件打开、点击、会议、通话和备注
- 自定义对象支持 - 将 HubSpot 自定义对象映射到 Brevo 属性
- 工作流触发 - 使用 HubSpot 生命周期阶段变化触发 Brevo 自动化
- Webhook 事件 - CRM 数据变更的实时通知
先决条件
开始前,请确认你具备:
- HubSpot 账户(Free、Starter、Professional 或 Enterprise)
- 拥有所需 scope 的 HubSpot 私有应用或 OAuth 应用
- 具备 API 访问权限的 Brevo 账户
- Tajo 账户
身份验证
私有应用访问令牌(推荐)
在 HubSpot 中创建私有应用,以实现具备细粒度 scope 控制的 API 直接访问。
- 进入 HubSpot Settings > Integrations > Private Apps
- 创建一个新的私有应用
- 配置所需的 scope
- 复制访问令牌
curl -X GET "https://api.hubapi.com/crm/v3/objects/contacts" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json"OAuth 2.0
对需要用户授权的多账户集成,请使用 OAuth 2.0。
# Authorization URLhttps://app.hubspot.com/oauth/authorize?client_id={client_id}&scope=crm.objects.contacts.read&redirect_uri={redirect_uri}所需 Scope
crm.objects.contacts.readcrm.objects.contacts.writecrm.objects.companies.readcrm.objects.deals.readcrm.objects.deals.writecrm.objects.custom.readcrm.schemas.custom.read配置
基础设置
connectors: hubspot: enabled: true access_token: "${HUBSPOT_ACCESS_TOKEN}"
# Data sync options sync: contacts: true companies: true deals: true tickets: true engagements: true
# Sync direction direction: bidirectional # or 'hubspot_to_brevo' | 'brevo_to_hubspot'
# List assignment in Brevo lists: all_contacts: 10 qualified_leads: 11 customers: 12字段映射
将 HubSpot 属性映射到 Brevo 联系人属性:
默认映射
| Parameter | Type | Description |
|---|---|---|
email required | string | 联系人邮箱(主标识) |
firstname optional | string | 映射到 Brevo 中的 FIRSTNAME 属性 |
lastname optional | string | 映射到 Brevo 中的 LASTNAME 属性 |
phone optional | string | 映射到 SMS 属性,用于 WhatsApp/SMS |
company optional | string | 关联的公司名称 |
lifecyclestage optional | string | HubSpot 生命周期阶段(subscriber、lead、MQL、SQL、customer) |
hs_lead_status optional | string | 线索评估状态 |
hubspot_owner_id optional | string | 指派的销售负责人 ID |
自定义属性映射
field_mapping: # Standard fields email: email firstname: FIRSTNAME lastname: LASTNAME phone: SMS
# CRM fields lifecyclestage: LIFECYCLE_STAGE hs_lead_status: LEAD_STATUS company: COMPANY_NAME
# Deal metrics hs_total_deal_value: DEAL_VALUE num_associated_deals: DEAL_COUNT
# Custom properties preferred_channel: PREFERRED_CHANNEL customer_segment: SEGMENTAPI 端点
CRM 对象
| 方法 | 端点 | 说明 |
|---|---|---|
GET | /crm/v3/objects/contacts | 列出联系人 |
POST | /crm/v3/objects/contacts | 创建联系人 |
PATCH | /crm/v3/objects/contacts/{id} | 更新联系人 |
GET | /crm/v3/objects/companies | 列出公司 |
GET | /crm/v3/objects/deals | 列出交易 |
POST | /crm/v3/objects/deals | 创建交易 |
GET | /crm/v3/objects/tickets | 列出工单 |
关联关系
| 方法 | 端点 | 说明 |
|---|---|---|
GET | /crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType} | 获取关联 |
PUT | /crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId} | 创建关联 |
互动记录
| 方法 | 端点 | 说明 |
|---|---|---|
GET | /crm/v3/objects/calls | 列出通话互动 |
GET | /crm/v3/objects/emails | 列出邮件互动 |
GET | /crm/v3/objects/meetings | 列出会议 |
GET | /crm/v3/objects/notes | 列出备注 |
GET | /crm/v3/objects/tasks | 列出任务 |
事件
联系人事件
| 事件 | 触发条件 | 适用场景 |
|---|---|---|
contact.creation | 创建新联系人 | 触发欢迎流程 |
contact.propertyChange | 联系人属性更新 | 属性同步 |
contact.merge | 联系人合并 | 去重处理 |
contact.deletion | 联系人被删除 | 在 Brevo 中清理 |
交易事件
| 事件 | 触发条件 | 适用场景 |
|---|---|---|
deal.creation | 创建新交易 | 销售通知 |
deal.propertyChange | 交易阶段变更 | 管道自动化 |
deal.deletion | 交易被移除 | 收入报表 |
公司事件
| 事件 | 触发条件 | 适用场景 |
|---|---|---|
company.creation | 添加新公司 | ABM 营销 |
company.propertyChange | 公司数据更新 | 企业画像同步 |
代码示例
初始化连接器
import { TajoClient } from '@tajo/sdk';
const tajo = new TajoClient({ apiKey: process.env.TAJO_API_KEY, brevoApiKey: process.env.BREVO_API_KEY});
// Connect HubSpotawait tajo.connectors.connect('hubspot', { accessToken: process.env.HUBSPOT_ACCESS_TOKEN});运行联系人同步
// Full bidirectional syncawait tajo.connectors.sync('hubspot', { type: 'full', resources: ['contacts', 'companies', 'deals'], direction: 'bidirectional', since: '2023-01-01'});
// Check sync statusconst status = await tajo.connectors.status('hubspot');console.log(status);// {// connected: true,// lastSync: '2024-01-15T10:30:00Z',// contactsSynced: 34200,// companiesSynced: 5100,// dealsSynced: 2340// }处理 Webhook 事件
// Handle HubSpot webhook notificationsapp.post('/webhooks/hubspot', async (req, res) => { const signature = req.get('X-HubSpot-Signature-v3');
// Verify webhook signature if (!verifyHubSpotSignature(req.body, signature)) { return res.status(401).send('Unauthorized'); }
for (const event of req.body) { await tajo.connectors.handleWebhook('hubspot', { eventType: event.subscriptionType, objectId: event.objectId, propertyName: event.propertyName, propertyValue: event.propertyValue }); }
res.status(200).send('OK');});速率限制
HubSpot 按私有应用或 OAuth 应用维度应用速率限制:
| 套餐 | 速率限制 | 峰值限制 |
|---|---|---|
| Free/Starter | 100 请求/10 秒 | 150 请求/10 秒 |
| Professional | 150 请求/10 秒 | 200 请求/10 秒 |
| Enterprise | 200 请求/10 秒 | 250 请求/10 秒 |
| API 加购 | 200 请求/10 秒 | 250 请求/10 秒 |
其他限制:
- Search API:5 请求/秒/应用
- 批量操作:每批 100 条记录
- 每日限额:500,000 请求/天(OAuth 应用)
速率限制处理
超出限制时 HubSpot 会返回 429 Too Many Requests。请使用指数退避,并监控 X-HubSpot-RateLimit-* 响应头。
故障排查
常见问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 401 Unauthorized | token 过期或无效 | 重新生成私有应用 token 或刷新 OAuth token |
| 联系人未同步 | 缺少 email 属性 | HubSpot 联系人必须有邮箱才能同步到 Brevo |
| 重复联系人 | 没有去重规则 | 在 HubSpot 中配置合并规则 |
| 未收到 webhook | 订阅未激活 | 重新注册 webhook 订阅 |
| 属性未映射 | 自定义属性未创建 | 请先在 HubSpot 中创建该属性 |
调试模式
开启详细日志:
connectors: hubspot: debug: true log_level: verbose log_webhooks: true连接测试
tajo connectors test hubspot# ✓ API connection successful# ✓ Contacts readable# ✓ Companies readable# ✓ Deals readable# ✓ Webhooks registered最佳实践
- 优先使用私有应用而非 API Key - API Key 已被弃用,使用私有应用更安全
- 谨慎实现双向同步 - 通过追踪同步来源避免无限循环
- 映射生命周期阶段 - 用 HubSpot 生命周期阶段在 Brevo 中分群
- 批量请求 API - 使用批量端点进行批量操作,保持在速率限制内
- 监控 webhook 送达 - 设置重试逻辑和死信处理
- 使用增量同步 - 通过
lastmodifieddate属性只同步变更记录
安全
- 私有应用令牌 - 具备细粒度权限的 scoped 访问令牌
- OAuth 2.0 - 行业标准授权协议,支持 refresh token 轮换
- Webhook 签名 - 基于 HMAC 的签名验证(v3)
- TLS 加密 - 所有 API 通信传输加密
- Scope 权限 - 集成按最小必要 scope 授权