HubSpot コネクター
HubSpot コネクター
HubSpot CRM を Tajo 経由で Brevo に接続して、双方向のコンタクト同期、取引追跡、エンゲージメントデータ、両プラットフォームにまたがる統一されたマーケティングオートメーションを実現します。
概要
| 項目 | 値 |
|---|---|
| プラットフォーム | HubSpot |
| カテゴリー | CRM |
| セットアップ難易度 | 中 |
| 公式統合 | あり |
| 同期データ | コンタクト、企業、取引、チケット、イベント |
| API ベース URL | https://api.hubapi.com |
機能
- 双方向コンタクト同期 - HubSpot と Brevo の間でコンタクトをリアルタイム同期
- 取引パイプライン追跡 - 売上ベースのセグメンテーションに取引ステージと金額を同期
- 企業データ同期 - コンタクトを企業レコードとファーモグラフィックデータに紐付け
- チケット統合 - カスタマーヘルススコアリング向けにサポートチケットを追跡
- エンゲージメント追跡 - メール開封、クリック、会議、通話、メモを同期
- カスタムオブジェクト対応 - HubSpot カスタムオブジェクトを Brevo 属性にマッピング
- ワークフロートリガー - HubSpot ライフサイクルステージ変更で Brevo 自動化をトリガー
- ウェブフックイベント - CRM データ変更のリアルタイム通知
前提条件
開始する前に、以下をご用意ください。
- HubSpot アカウント (Free、Starter、Professional、Enterprise いずれも可)
- 必要なスコープを持つ HubSpot プライベートアプリまたは OAuth アプリ
- API アクセス付きの Brevo アカウント
- Tajo アカウント
認証
プライベートアプリのアクセストークン (推奨)
HubSpot にプライベートアプリを作成し、きめ細かいスコープ管理で直接 API アクセスを行います。
- HubSpot Settings > Integrations > Private Apps に移動
- 新規プライベートアプリを作成
- 必要なスコープを設定
- アクセストークンをコピー
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}必要なスコープ
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 | WhatsApp/SMS 用の 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// }ウェブフックイベントの処理
// 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 | 期限切れまたは無効なトークン | プライベートアプリトークンを再生成または OAuth トークンをリフレッシュ |
| コンタクトが同期されない | email プロパティ不足 | HubSpot コンタクトは Brevo 同期にメール必須 |
| 重複コンタクト | 重複排除ルール未設定 | HubSpot でマージルールを設定 |
| ウェブフック未受信 | 購読未有効 | ウェブフック購読を再登録 |
| プロパティ未マッピング | カスタムプロパティ未作成 | まず 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 キーよりプライベートアプリを利用 - API キーは非推奨。セキュリティ向上のためプライベートアプリを使用
- 双方向同期は慎重に実装 - 同期元を追跡して無限ループを防止
- ライフサイクルステージをマッピング - HubSpot ライフサイクルステージで Brevo 内のコンタクトをセグメント化
- API リクエストをバッチ化 - バルク操作にバッチエンドポイントを利用してレート制限内に収める
- ウェブフック配信を監視 - リトライロジックとデッドレター処理を設定
- 増分同期を使用 -
lastmodifieddateプロパティで変更分のみ同期
セキュリティ
- プライベートアプリトークン - きめ細かい権限のスコープ付きアクセストークン
- OAuth 2.0 - リフレッシュトークンローテーション対応の業界標準認可
- ウェブフック署名 - HMAC ベースの署名検証 (v3)
- TLS 暗号化 - すべての API 通信は転送時に暗号化
- スコープ権限 - 統合ごとに必要最小限のスコープアクセス