고객 데이터는 허브스팟에 차곡차곡 쌓이는데, 슬랙 알림은 따로 받고, 정산은 ERP에서 또 따로 돌리고 계신가요?
사용하는 도구가 늘어날수록, 같은 데이터를 여기저기 수동으로 옮기는 일이 많아집니다.
이 반복 작업을 없애는 열쇠가 바로 허브스팟 API입니다.
허브스팟 API는 외부 시스템과 허브스팟을 직접 연결해, 데이터를 자동으로 주고받게 해주는 통로기 때문이죠.
이 글에서는 허브스팟 API의 기본 개념부터 인증 방법, 주요 엔드포인트, 그리고 슬랙·구글시트·ERP 같은 실전 연동 예시까지 순서대로 정리합니다. 코드 예시도 함께 담아두긴 했지만, 혹시 개발자가 아니더라도 ‘무엇이 어떻게 연결되는지’ 큰 그림을 잡으실 수 있도록 풀어 설명드리겠습니다.
허브스팟 API란 무엇이고, 무엇을 연결할 수 있나요?
API는 두 시스템이 정해진 약속에 따라 데이터를 주고받는 창구입니다. 허브스팟 API는 그중에서도 REST 방식을 따릅니다. 웹 주소(URL)로 요청을 보내면, 허브스팟이 JSON 형태로 데이터를 돌려주는 구조입니다.
모든 요청은 https://api.hubapi.com 이라는 기본 주소에서 시작합니다. 여기에 HTTP 메서드(GET·POST·PATCH·DELETE)를 붙여 조회·생성·수정·삭제를 처리합니다.
허브스팟의 데이터는 몇 가지 핵심 객체(Object 또는 Record라고도 합니다)로 나뉩니다.
연락처(Contact), 회사(Company), 거래(Deal), 티켓(Ticket)이 대표적이죠.
이 객체들을 CRM API로 다루는 것이 연동의 출발점입니다.
그렇다면 허브스팟 API로 실제로 무엇을 할 수 있을까요?
- 외부 폼이나 웹사이트에서 들어온 리드를 허브스팟 연락처로 자동 생성하기
- 허브스팟의 거래 단계가 바뀌면 슬랙이나 사내 메신저로 알림 보내기
- 구글시트와 연락처 데이터를 양방향으로 맞추기
- ERP·회계 시스템과 회사·거래 정보를 주기적으로 동기화하기
결국, 허브스팟 API로 할 수 있는 건 허브스팟 안의 데이터를 바깥으로 꺼내거나, 바깥의 데이터를 허브스팟으로 밀어 넣는 일이라고 할 수 있습니다. 이 두 가지 방식만 이해하면 대부분의 연동 시나리오를 이해할 수 있습니다.
인증부터 시작하기 : Private App과 OAuth
데이터를 주고받으려면, 먼저 ‘누가 요청하는지’를 증명해야 합니다.
허브스팟 API의 인증 방식은 크게 두 가지입니다.
참고로, 먼저 알아둘 점이 있습니다. 과거에 쓰이던 API Key 방식은 2022년에 지원이 종료됐다는 것입니다. 기존의 신규 키 발급은 2022년 7월 15일부터 막혔고, 사용하시던 키도 22년 11월 30일부터 작동하지 않습니다. 따라서 지금 새로 연동하신다면, 아래의 두 가지 방식 중 하나를 써야 합니다.
1) Private App – 내 계정 안에서 쓰는 연동에 사용
우리 회사 계정 하나에서만 쓰는 연동이라면 Private App이 가장 간단합니다. 허브스팟 계정의 ‘설정 → 통합(Integrations) → Private Apps’에서 앱을 만들고, 필요한 접근 범위(scope)를 지정하면 액세스 토큰이 발급됩니다.
이 토큰을 모든 요청 헤더에 담아 보내면 인증이 끝납니다.
Authorization: Bearer YOUR_ACCESS_TOKEN
토큰 하나로 인증이 끝나니, 사내 자동화나 단일 계정 연동에는 이 방식이 잘 맞습니다.
2) OAuth 2.0 – 여러 고객사에 배포하는 앱에 사용
API 연동을 한 뒤 여러 허브스팟 계정에 배포하거나 마켓플레이스에 공개 앱으로 올린다면 OAuth 2.0이 필요합니다. 사용자를 허브스팟 인증 화면으로 보내 권한을 승인받고, 그 대가로 액세스 토큰과 갱신 토큰(refresh token)을 받는 흐름입니다.
액세스 토큰은 유효 기간이 있어, 만료되면 갱신 토큰으로 다시 받아 써야 합니다. 토큰을 안전하게 저장하고 갱신하는 책임은 앱 쪽에 있습니다.
따라서 정리하자면, 우리 계정 내부 연동은 Private App, 여러 고객사에 배포하는 공개 앱은 OAuth을 사용하면 된다고 할 수 있습니다. 대부분의 사내 연동은 Private App으로 충분합니다.
주요 엔드포인트와 첫 번째 API 호출
인증 토큰을 준비했다면, 이제 실제로 데이터를 다뤄 볼 차례입니다. 허브스팟 CRM API(v3)의 엔드포인트 (다른 소프트웨어 시스템이 특정 API(프로그램)와 통신하여 데이터나 기능을 주고받을 수 있도록 허용하는 ‘접근 지점(URL 또는 URI)) 는 일정한 패턴을 따릅니다.
- GET /crm/v3/objects/contacts : 목록 조회
- POST /crm/v3/objects/contacts : 단건 생성
- POST /crm/v3/objects/contacts/batch/create : 여러 건 생성
- POST /crm/v3/objects/contacts/search : 조건 검색
여기서 객체 이름(contacts)만 companies, deals, tickets로 바꾸면 다른 데이터에도 같은 방식이 적용됩니다.
규칙이 일관적이라, 하나만 익히면 나머지는 금방 응용할 수 있는 거죠.
예를 들어, 새 연락처 하나를 만드는 요청은 이렇게 하시면 됩니다.
curl -X POST https://api.hubapi.com/crm/v3/objects/contacts \
-H “Authorization: Bearer YOUR_ACCESS_TOKEN” \
-H “Content-Type: application/json” \
-d ‘{“properties”:{“email”:”jane@example.com”,”firstname”:”지은”,”lastname”:”김”}}’
여기서 properties 안에 채우고 싶은 속성을 넣으면, 허브스팟이 새 연락처를 만들고 그 정보를 다시 돌려줍니다.
연락처를 만들면서 기존 회사나 거래와 연결하고 싶다면 associations 항목으로 함께 묶을 수도 있습니다.
이렇게 외부 시스템에서 데이터를 밀어 넣는 흐름 하나만 만들어 두면, 스프레드시트나 폼에 흩어진 리드를 허브스팟 CRM으로 모으는 작업을 사람 손 없이 자동화할 수 있습니다.
실시간 연동의 핵심, 웹훅(Webhook)
지금까지는 우리가 허브스팟에 ‘요청을 보내는’ 방향이었습니다.
반대로 허브스팟에서 일이 생겼을 때 외부로 알려주는 방법도 있습니다. 이게 바로 웹훅입니다.
웹훅은 특정 이벤트가 발생하면 허브스팟이 우리가 지정한 주소로 데이터를 POST로 보내주는 구독형 알림입니다.
우리가 1분마다 ‘새 연락처 있나요?’라고 물어볼 필요 없이, 일이 생긴 순간 허브스팟이 먼저 알려주는 방식입니다.
구독할 수 있는 대표적인 이벤트는 다음과 같습니다.
- contact.creation : 새 연락처가 생성됐을 때
- contact.propertyChange : 연락처 속성 값이 바뀌었을 때
- deal.creation : 새 거래가 만들어졌을 때
웹훅을 쓸 때 빠뜨리면 안 되는 것이 요청 검증입니다. 외부에서 우리 주소로 가짜 요청을 보낼 수도 있으니까요.
허브스팟은 요청 헤더에 서명(X-HubSpot-Signature-v3)과 타임스탬프를 함께 보냅니다.
앱 시크릿으로 같은 값을 계산해 맞는지 확인하고, 5분이 지난 오래된 요청은 거부하면 됩니다.
이 검증만 제대로 해두면, 실시간 연동의 신뢰성이 크게 올라가게 되죠.
실전 연동 시나리오 : 슬랙·구글시트·ERP
개념을 익혔으니, 현장에서 가장 많이 쓰는 세 가지 연동을 살펴보겠습니다.
1) 슬랙 : 새 거래·리드 실시간 알림
영업팀이 가장 반기는 연동입니다. 허브스팟에서 deal.creation 웹훅이 발생하면, 중간 서버가 이를 받아 슬랙의 수신 웹훅(Incoming Webhook)으로 메시지를 보냅니다. 큰 거래가 들어온 순간 팀 채널에 자동으로 알림이 뜨니, 대응이 빨라집니다.
2) 구글 시트 : 데이터를 양방향으로 맞추기
리포트나 단순 관리는 여전히 시트가 편할 때가 있습니다. CRM API의 연락처·회사 엔드포인트를 쓰면, 허브스팟의 데이터를 시트로 내려받거나(GET·search) 시트에 입력한 내용을 허브스팟으로 올릴(POST·PATCH) 수 있습니다. 양쪽을 잇는 간단한 스크립트만 있으면 됩니다.
3) ERP : 회사·거래 정보 동기화
회계나 재고를 관리하는 ERP와 허브스팟을 따로 쓰면, 같은 거래를 양쪽에 두 번 입력하게 됩니다. 회사와 거래 객체를 조회·생성·검색하고 서로 연결(association)하면, 영업에서 확정된 거래가 ERP로, ERP의 고객 정보가 허브스팟으로 자동으로 연동됩니다.
세 가지 연동의 경우, 모두 원리는 동일합니다.
바로 허브스팟 API로 데이터를 꺼내고, 웹훅으로 변화를 감지하는 거죠.
Rate Limit과 안정적인 연동 운영
연동을 운영하다 보면 꼭 마주치는 것이 호출 한도(Rate Limit)입니다.
허브스팟은 짧은 시간에 너무 많은 요청이 몰리지 않도록 한도를 둡니다.
Private App 기준으로 정리하면 다음과 같습니다.
10초당 한도는 앱별로 적용되고, 하루 한도는 계정 안의 모든 앱이 함께 나눠 씁니다.
한도를 넘으면 허브스팟은 429 응답을 돌려줍니다.
응답 헤더에는 남은 호출 수(X-HubSpot-RateLimit-Remaining)가 들어 있어, 이 값을 보고 요청 속도를 조절하면 안정적으로 운영할 수 있습니다. 대량 작업은 한 건씩 보내기보다 배치(batch) 엔드포인트(대규모 데이터나 여러 개의 요청을 한 번에 묶어서 처리(Batch)하기 위해 설계된 URL 주소 또는 네트워크 접속 경로)로 묶어 보내는 편이 한도 관리에 유리합니다.
꼭 코드를 직접 짜야만 연동할 수 있나요?
모든 연동을 직접 개발할 필요는 없습니다. 표준적인 시스템 연결이라면, 마켓플레이스의 기본 통합이나 워크플로우 기반 자동화로 코드 없이 처리할 수 있는 경우도 많습니다. 우리만의 복잡한 로직이 필요할 때만 API를 직접 다루면 됩니다.
자세한 한도표와 엔드포인트 명세는 HubSpot 공식 개발자 문서에서 확인하실 수 있습니다.
자주 묻는 질문
Q1. 개발자가 아니어도 허브스팟 API를 쓸 수 있나요?
직접 코드를 짜려면 기본적인 개발 지식이 필요합니다. 다만, 간단한 연동은 노코드 도구나 마켓플레이스 통합으로 해결되는 경우가 많습니다. 무엇을 연동할지부터 정리한 뒤, 코드와 노코드 중 적합한 방법을 고르시길 권합니다.
Q2. Private App과 OAuth 중 무엇을 골라야 하나요?
우리 회사 계정 하나에서만 쓰는 사내 연동이라면 Private App이 간단합니다. 여러 고객사에 배포하거나 공개 앱으로 만들 계획이라면 OAuth 2.0이 필요합니다.
Q3. 호출 한도를 넘으면 어떻게 되나요?
429 응답이 돌아오고 해당 요청은 처리되지 않습니다. 응답 헤더의 남은 호출 수를 참고해 속도를 조절하고, 대량 작업은 배치로 묶으면 한도를 넘기지 않고 운영할 수 있습니다.
허브스팟 API의 진짜 가치는 코드 자체가 아니라, 흩어진 데이터를 하나로 잇는 데 있습니다.
어떤 데이터를, 어느 방향으로, 어떻게 흐르게 할지부터 정리하면 연동의 절반은 끝난 셈입니다.
처음 연동을 설계하거나, 데이터 구조부터 제대로 잡고 싶다면
허브스팟 온보딩 과정에서 함께 점검해 보실 수 있습니다.
경성솔루션은 허브스팟 도입과 연동을 고민 중인 기업이 무엇을 자동화할 수 있고 무엇이 어려운지 분명히 가려,
우리 조직에 맞는 방향을 찾도록 돕고 있습니다.
만약 고민이 되신다면 미팅을 신청해보세요.
30분 ~ 1시간 무료 미팅을 통해 무엇이 가능하고 어려운지 분명히 나눠 말씀드리겠습니다.
경성솔루션은 무조건 다 된다는 무모한 약속은 하지 않습니다.
정확한 진단을 바탕으로 ‘솔직한 제안’을,
남들에게도 똑같이 제공하는 일괄적인 설명이 아니라 우리 조직만의 정답을 찾아드립니다.
함께 읽으면 좋은 글
► 허브스팟 사용법 : 초보자를 위한 CRM 단계별 시작 가이드
► 허브스팟 온보딩 서비스 안내
► 허브스팟 도입 문의
