HubSpot コネクター

HubSpot コネクター

HubSpot CRM を Tajo 経由で Brevo に接続して、双方向のコンタクト同期、取引追跡、エンゲージメントデータ、両プラットフォームにまたがる統一されたマーケティングオートメーションを実現します。

概要

項目
プラットフォームHubSpot
カテゴリーCRM
セットアップ難易度
公式統合あり
同期データコンタクト、企業、取引、チケット、イベント
API ベース URLhttps://api.hubapi.com

機能

  • 双方向コンタクト同期 - HubSpot と Brevo の間でコンタクトをリアルタイム同期
  • 取引パイプライン追跡 - 売上ベースのセグメンテーションに取引ステージと金額を同期
  • 企業データ同期 - コンタクトを企業レコードとファーモグラフィックデータに紐付け
  • チケット統合 - カスタマーヘルススコアリング向けにサポートチケットを追跡
  • エンゲージメント追跡 - メール開封、クリック、会議、通話、メモを同期
  • カスタムオブジェクト対応 - HubSpot カスタムオブジェクトを Brevo 属性にマッピング
  • ワークフロートリガー - HubSpot ライフサイクルステージ変更で Brevo 自動化をトリガー
  • ウェブフックイベント - CRM データ変更のリアルタイム通知

前提条件

開始する前に、以下をご用意ください。

  1. HubSpot アカウント (Free、Starter、Professional、Enterprise いずれも可)
  2. 必要なスコープを持つ HubSpot プライベートアプリまたは OAuth アプリ
  3. API アクセス付きの Brevo アカウント
  4. Tajo アカウント

認証

プライベートアプリのアクセストークン (推奨)

HubSpot にプライベートアプリを作成し、きめ細かいスコープ管理で直接 API アクセスを行います。

  1. HubSpot Settings > Integrations > Private Apps に移動
  2. 新規プライベートアプリを作成
  3. 必要なスコープを設定
  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}

必要なスコープ

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

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: 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
// }

ウェブフックイベントの処理

// 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 Unauthorized期限切れまたは無効なトークンプライベートアプリトークンを再生成または OAuth トークンをリフレッシュ
コンタクトが同期されないemail プロパティ不足HubSpot コンタクトは Brevo 同期にメール必須
重複コンタクト重複排除ルール未設定HubSpot でマージルールを設定
ウェブフック未受信購読未有効ウェブフック購読を再登録
プロパティ未マッピングカスタムプロパティ未作成まず 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 キーよりプライベートアプリを利用 - API キーは非推奨。セキュリティ向上のためプライベートアプリを使用
  2. 双方向同期は慎重に実装 - 同期元を追跡して無限ループを防止
  3. ライフサイクルステージをマッピング - HubSpot ライフサイクルステージで Brevo 内のコンタクトをセグメント化
  4. API リクエストをバッチ化 - バルク操作にバッチエンドポイントを利用してレート制限内に収める
  5. ウェブフック配信を監視 - リトライロジックとデッドレター処理を設定
  6. 増分同期を使用 - lastmodifieddate プロパティで変更分のみ同期

セキュリティ

  • プライベートアプリトークン - きめ細かい権限のスコープ付きアクセストークン
  • OAuth 2.0 - リフレッシュトークンローテーション対応の業界標準認可
  • ウェブフック署名 - HMAC ベースの署名検証 (v3)
  • TLS 暗号化 - すべての API 通信は転送時に暗号化
  • スコープ権限 - 統合ごとに必要最小限のスコープアクセス

関連リソース

Subscribe to updates

developer-docs

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

AIアシスタント

こんにちは!ドキュメントについて何でもお聞きください。

Brevoで無料で始める