HubSpot 커넥터

HubSpot 커넥터

HubSpot CRM을 Tajo를 통해 Brevo에 연결하여 양방향 연락처 동기화, 거래 추적, 인게이지먼트 데이터, 그리고 두 플랫폼 전반에 걸친 통합 마케팅 자동화를 구현하세요.

개요

주요 기능

• 양방향 연락처 동기화 - HubSpot과 Brevo 간의 연락처를 실시간으로 동기화합니다
• 거래 파이프라인 추적 - 매출 기반 세그먼테이션을 위해 거래 단계와 금액을 동기화합니다
• 회사 데이터 동기화 - 연락처를 회사 레코드 및 기업 정보 데이터와 연결합니다
• 티켓 통합 - 고객 헬스 스코어링을 위해 지원 티켓을 추적합니다
• 인게이지먼트 추적 - 이메일 오픈, 클릭, 미팅, 통화, 메모를 동기화합니다
• 커스텀 오브젝트 지원 - HubSpot 커스텀 오브젝트를 Brevo 속성에 매핑합니다
• 워크플로우 트리거 - HubSpot 라이프사이클 단계 변경을 사용해 Brevo 자동화를 트리거합니다
• 웹훅 이벤트 - CRM 데이터 변경에 대한 실시간 알림

사전 준비 사항

시작하기 전에 다음 사항이 준비되어 있어야 합니다.

1. HubSpot 계정 (Free, Starter, Professional 또는 Enterprise)
2. 필수 스코프를 갖춘 HubSpot private app 또는 OAuth app
3. API 액세스가 활성화된 Brevo 계정
4. Tajo 계정

인증

Private App 액세스 토큰 (권장)

세분화된 스코프 제어와 함께 직접 API에 액세스하려면 HubSpot에서 private app을 생성하세요.

1. HubSpot Settings > Integrations > Private Apps로 이동합니다
2. 새 private app을 생성합니다
3. 필수 스코프를 설정합니다
4. 액세스 토큰을 복사합니다

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 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 연락처 속성에 매핑합니다.

커스텀 속성 매핑

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 오브젝트

연관 관계

인게이지먼트

이벤트

연락처 이벤트

거래 이벤트

회사 이벤트

코드 예제

커넥터 초기화

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은 private app 또는 OAuth app별로 요청 제한을 적용합니다.

추가 제한 사항:

• Search API: 앱당 초당 5회
• 배치 작업: 배치 요청당 100개 레코드
• 일일 제한: 일일 500,000회 요청 (OAuth app)

문제 해결

일반적인 문제

디버그 모드

상세 로깅 활성화:

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

모범 사례

1. API 키보다 private app 사용 - API 키는 deprecated 되었으므로 보안을 위해 private app을 사용하세요
2. 양방향 동기화를 신중하게 구현 - 동기화 소스를 추적하여 무한 루프를 방지하세요
3. 라이프사이클 단계 매핑 - HubSpot 라이프사이클 단계를 사용해 Brevo에서 연락처를 세분화하세요
4. API 요청 배치 처리 - 요청 제한을 준수하기 위해 대량 작업에는 배치 엔드포인트를 사용하세요
5. 웹훅 전송 모니터링 - 재시도 로직과 dead letter 처리를 설정하세요
6. 증분 동기화 사용 - lastmodifieddate 속성을 사용해 변경된 레코드만 동기화하세요

보안

• Private App 토큰 - 세분화된 권한을 가진 스코프 기반 액세스 토큰
• OAuth 2.0 - 리프레시 토큰 순환이 적용된 업계 표준 인증
• 웹훅 서명 - HMAC 기반 서명 검증 (v3)
• TLS 암호화 - 모든 API 통신은 전송 중 암호화됩니다
• 스코프 권한 - 통합별 최소 필요 스코프 액세스

관련 리소스

• HubSpot API Documentation
• HubSpot Authentication Guide
• Salesforce 커넥터
• Customer Sync Skill
• Brevo Contacts API