HubSpot 连接器

HubSpot 连接器

通过 Tajo 将你的 HubSpot CRM 连接到 Brevo,实现双向联系人同步、交易追踪、互动数据同步,以及跨两大平台的统一营销自动化。

概览

属性
平台HubSpot
类别CRM
部署复杂度中等
官方集成
同步数据联系人、公司、交易、工单、事件
API Base URLhttps://api.hubapi.com

功能特性

  • 双向联系人同步 - 实时在 HubSpot 与 Brevo 之间保持联系人同步
  • 交易管道追踪 - 同步交易阶段和金额,用于基于收入的分群
  • 公司数据同步 - 将联系人关联到公司记录及其企业画像数据
  • 工单集成 - 追踪支持工单,用于客户健康度评分
  • 互动追踪 - 同步邮件打开、点击、会议、通话和备注
  • 自定义对象支持 - 将 HubSpot 自定义对象映射到 Brevo 属性
  • 工作流触发 - 使用 HubSpot 生命周期阶段变化触发 Brevo 自动化
  • Webhook 事件 - CRM 数据变更的实时通知

先决条件

开始前,请确认你具备:

  1. HubSpot 账户(Free、Starter、Professional 或 Enterprise)
  2. 拥有所需 scope 的 HubSpot 私有应用或 OAuth 应用
  3. 具备 API 访问权限的 Brevo 账户
  4. Tajo 账户

身份验证

私有应用访问令牌(推荐)

在 HubSpot 中创建私有应用,以实现具备细粒度 scope 控制的 API 直接访问。

  1. 进入 HubSpot Settings > Integrations > Private Apps
  2. 创建一个新的私有应用
  3. 配置所需的 scope
  4. 复制访问令牌
Terminal window
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。

Terminal window
# Authorization URL
https://app.hubspot.com/oauth/authorize?client_id={client_id}&scope=crm.objects.contacts.read&redirect_uri={redirect_uri}

所需 Scope

crm.objects.contacts.read
crm.objects.contacts.write
crm.objects.companies.read
crm.objects.deals.read
crm.objects.deals.write
crm.objects.custom.read
crm.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: SEGMENT

API 端点

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 HubSpot
await tajo.connectors.connect('hubspot', {
accessToken: process.env.HUBSPOT_ACCESS_TOKEN
});

运行联系人同步

// Full bidirectional sync
await tajo.connectors.sync('hubspot', {
type: 'full',
resources: ['contacts', 'companies', 'deals'],
direction: 'bidirectional',
since: '2023-01-01'
});
// Check sync status
const 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 notifications
app.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/Starter100 请求/10 秒150 请求/10 秒
Professional150 请求/10 秒200 请求/10 秒
Enterprise200 请求/10 秒250 请求/10 秒
API 加购200 请求/10 秒250 请求/10 秒

其他限制:

  • Search API:5 请求/秒/应用
  • 批量操作:每批 100 条记录
  • 每日限额:500,000 请求/天(OAuth 应用)

速率限制处理

超出限制时 HubSpot 会返回 429 Too Many Requests。请使用指数退避,并监控 X-HubSpot-RateLimit-* 响应头。

故障排查

常见问题

问题原因解决方案
401 Unauthorizedtoken 过期或无效重新生成私有应用 token 或刷新 OAuth token
联系人未同步缺少 email 属性HubSpot 联系人必须有邮箱才能同步到 Brevo
重复联系人没有去重规则在 HubSpot 中配置合并规则
未收到 webhook订阅未激活重新注册 webhook 订阅
属性未映射自定义属性未创建请先在 HubSpot 中创建该属性

调试模式

开启详细日志:

connectors:
hubspot:
debug: true
log_level: verbose
log_webhooks: true

连接测试

Terminal window
tajo connectors test hubspot
# ✓ API connection successful
# ✓ Contacts readable
# ✓ Companies readable
# ✓ Deals readable
# ✓ Webhooks registered

最佳实践

  1. 优先使用私有应用而非 API Key - API Key 已被弃用,使用私有应用更安全
  2. 谨慎实现双向同步 - 通过追踪同步来源避免无限循环
  3. 映射生命周期阶段 - 用 HubSpot 生命周期阶段在 Brevo 中分群
  4. 批量请求 API - 使用批量端点进行批量操作,保持在速率限制内
  5. 监控 webhook 送达 - 设置重试逻辑和死信处理
  6. 使用增量同步 - 通过 lastmodifieddate 属性只同步变更记录

安全

  • 私有应用令牌 - 具备细粒度权限的 scoped 访问令牌
  • OAuth 2.0 - 行业标准授权协议,支持 refresh token 轮换
  • Webhook 签名 - 基于 HMAC 的签名验证(v3)
  • TLS 加密 - 所有 API 通信传输加密
  • Scope 权限 - 集成按最小必要 scope 授权

相关资源

Subscribe to updates

developer-docs

Drop your email or phone number — we'll send you what matters next.

AI 助手

你好!关于文档有任何问题都可以问我。

免费开始使用Brevo