---
title: "HubSpot 커넥터"
description: "HubSpot CRM을 Tajo를 통해 Brevo와 연동하여 연락처, 회사, 거래, 티켓, 마케팅 데이터를 동기화하는 완벽 가이드입니다."
url: https://tajo.io/kr/docs/connectors/crm/hubspot/
markdown: https://tajo.io/kr/docs/connectors/crm/hubspot.md
lang: ko-KR
robots: noindex
---

Tajo 사전 이용 신청

이름과 회사 이메일 주소를 입력하세요. Tajo 이용 신청을 확인할 수 있는 링크를 이메일로 보내드립니다.

# HubSpot 커넥터

커넥터 상태: 개발 중 구축 중입니다. 아직 검증되지 않았습니다.

| 원본 필드 | 대상 필드 | 예시 값 |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

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

## 개요

| 속성 | 값 |
| --- | --- |
| **플랫폼** | HubSpot |
| **카테고리** | CRM |
| **설정 난이도** | 보통 |
| **공식 통합** | 아니오 |
| **동기화되는 데이터** | 연락처, 회사, 거래, 티켓, 이벤트 |
| **API 기본 URL** | `https://api.hubapi.com` |

## 주요 기능

- **양방향 연락처 동기화** - 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. 액세스 토큰을 복사합니다

```bash
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을 사용합니다.

```bash
# 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
```

## 설정

### 기본 설정

```yaml
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 |

#### 커스텀 속성 매핑

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

| Method | 엔드포인트 | 설명 |
| --- | --- | --- |
| `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` | 티켓 목록 조회 |

### 연관 관계

| Method | 엔드포인트 | 설명 |
| --- | --- | --- |
| `GET` | `/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}` | 연관 관계 조회 |
| `PUT` | `/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}` | 연관 관계 생성 |

### 인게이지먼트

| Method | 엔드포인트 | 설명 |
| --- | --- | --- |
| `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` | 새 회사 추가 | 계정 기반 마케팅 |
| `company.propertyChange` | 회사 데이터 업데이트 | 기업 정보 동기화 |

## 코드 예제

### 커넥터 초기화

```javascript
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
});
```

### 연락처 동기화 실행

```javascript
// 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
// }
```

### 웹훅 이벤트 처리

```javascript
// 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별로 요청 제한을 적용합니다.

| 플랜 | 요청 제한 | 버스트 제한 |
| --- | --- | --- |
| Free/Starter | 100회/10초 | 150회/10초 |
| Professional | 150회/10초 | 200회/10초 |
| Enterprise | 200회/10초 | 250회/10초 |
| API add-on | 200회/10초 | 250회/10초 |

추가 제한 사항:

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

요청 제한 처리

HubSpot은 제한을 초과하면 `429 Too Many Requests` 응답을 반환합니다. 지수 백오프를 사용하고 `X-HubSpot-RateLimit-*` 헤더를 모니터링하세요.

## 문제 해결

### 일반적인 문제

| 문제 | 원인 | 해결 방법 |
| --- | --- | --- |
| 401 Unauthorized | 토큰 만료 또는 유효하지 않음 | private app 토큰을 재생성하거나 OAuth 토큰을 새로 고치세요 |
| 연락처가 동기화되지 않음 | 이메일 속성 누락 | HubSpot 연락처에는 Brevo 동기화를 위한 이메일이 필요합니다 |
| 중복 연락처 | 중복 제거 규칙 없음 | HubSpot에서 병합 규칙을 구성하세요 |
| 웹훅 수신 안 됨 | 구독이 활성화되지 않음 | 웹훅 구독을 재등록하세요 |
| 속성이 매핑되지 않음 | 커스텀 속성이 생성되지 않음 | HubSpot에서 먼저 속성을 생성하세요 |

### 디버그 모드

상세 로깅 활성화:

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

### 연결 테스트

```bash
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](https://developers.hubspot.com/docs/api/overview)
- [HubSpot Authentication Guide](https://developers.hubspot.com/docs/api/working-with-oauth)
- [Salesforce 커넥터](https://tajo.io/kr/docs/connectors/crm/salesforce)
- [Customer Sync Skill](https://tajo.io/kr/docs/skills/data-sync/customer-sync)
- [Brevo Contacts API](https://tajo.io/kr/docs/contact-management)