여전히 HubSpot API 키를 찾고 계세요? 그만 찾으셔도 됩니다. HubSpot은 2022년 11월 30일에 정적 API 키를 단종했고, 현재 Node SDK(@hubspot/api-client, v14)도 API 키를 받아들이지 않습니다. 단일 계정 내부 도구에 적합한 인증 수단은 비공개 앱 액세스 토큰입니다. 이 가이드는 첫 연락처 생성 호출부터 서명 검증 웹훅까지, Node와 Python 모두에서 실제 HubSpot-대-내부 도구 동기화를 구축합니다.
빠른 답변: HubSpot API 통합은 커스텀 내부 도구가 HubSpot의 v3 REST API를 통해 CRM 데이터를 읽고 쓸 수 있게 합니다. 단일 계정 내부 도구의 경우, 비공개 앱 액세스 토큰으로 인증하면 됩니다(HubSpot은 2022년에 API 키를 단종함). 그 다음 폴링 대신 웹훅을 사용하여 실시간으로 변경사항을 동기화합니다.
다음을 빌드하게 됩니다:
- Node와 Python에서 비공개 앱 토큰 인증 및 첫 번째 연락처 생성 호출
- X-HubSpot-Signature-v3 서명을 검증하고 페이로드를 신뢰하는 웹훅 수신기
- 429 안전한 배치 100 동기화를 내부 티켓 또는 ERP 레코드로 수행
HubSpot API 통합이 커스텀 내부 도구에서 어떻게 작동하는가?
HubSpot API 통합은 커스텀 내부 도구(티켓팅 앱, ERP, 청구 대시보드, 고객 포털)를 HubSpot의 v3 REST API를 통해 HubSpot의 CRM에 연결합니다. 도구는 비공개 앱 액세스 토큰을 사용하여 HTTPS를 통해 CRM 객체(연락처, 거래, 회사 또는 커스텀 객체)를 읽고 쓰며, 실시간 변경사항은 웹훅을 통해 다시 흘러옵니다.
HubSpot의 CRM을 HTTP를 통해 통신하는 데이터베이스로 생각하세요. 모든 레코드는 유형과 ID를 가진 객체입니다. 당신이 구축 중인 HubSpot CRM API 통합은 두 가지 작업을 합니다. HubSpot에 데이터를 푸시하고(티켓이 열리면 연락처 생성), HubSpot에서 데이터를 가져옵니다(대시보드가 렌더링될 때 거래 읽기).
동기화는 두 방향 중 하나로 실행됩니다. 일방향 동기화는 HubSpot의 변경사항을 도구로 복사하거나, 도구의 변경사항을 HubSpot으로 복사합니다. 양방향 동기화는 둘 다 수행하며 루프 보호가 필요합니다(나중에 다룸). 그리고 매분 "뭔가 새로운 게 있나?"를 묻는 폴링 대신, 웹훅을 등록하면 HubSpot이 레코드가 변경되는 즉시 알려줍니다.
호스팅된 CRM을 통합하기보다는 데이터를 완전히 소유하려면, 오픈소스 CRM을 자체 호스팅하는 것이 다른 선택지이며 커밋하기 전에 검토할 가치가 있습니다. 하지만 HubSpot이 이미 신뢰할 수 있는 소스라면, API는 다른 모든 것이 이와 통신하는 방법입니다.
단일 계정 내부 도구의 경우, OAuth나 앱 마켓플레이스 리스팅이 필요하지 않습니다. 비공개 앱 토큰과 웹훅이 전체 통합입니다.
2026의 인증: HubSpot API 키가 더 이상 없는 이유
단일 계정 내부 도구를 위한 HubSpot API 인증은 비공개 앱 액세스 토큰을 사용합니다. 이는 HubSpot 계정에서 한 번 생성하는 정적 베어러 토큰이며, 도구가 액세스하는 객체에만 스코프됩니다. 새로고침 흐름이 없고 만료도 없습니다. OAuth는 공개 다중 계정 앱용이지, ops 팀이 내부에서 실행하는 대시보드용이 아닙니다.
비공개 앱 토큰 vs 단종된 API 키
이것이 이 검색 결과에 도달하는 개발자 중 절반을 혼동시키는 함정입니다. HubSpot은 2022년 11월 30일에 API 키를 단종했으며, 지금은 완전히 지원되지 않습니다. 자동완성은 여전히 "hubspot api key"를 제안합니다(근육 기억이 따라잡지 못했기 때문), 하지만 가져올 키가 없습니다. 비공개 앱을 사용하세요: 설정에서 생성하고, 필요한 스코프를 부여한 다음, Auth 탭에서 액세스 토큰을 복사합니다. HubSpot의 비공개 앱 개요는 설정을 다룹니다.
토큰 자체에 대한 두 가지 규칙이 있습니다. 최소 권한 원칙을 적용하세요. 도구가 거래만 읽고 연락처만 쓴다면, crm.objects.contacts.write와 crm.objects.deals.read만 요청하세요(그 이상은 안 됨). 그리고 토큰을 환경 변수나 시크릿 매니저에 보관하고, Authorization: Bearer 헤더로 전송하며, 하드코딩되거나 브라우저로 전송되지 않도록 하세요.
판결은 간단합니다. 내부 도구의 경우 비공개 앱 액세스 토큰을 사용하세요. OAuth는 나중에 다른 회사가 자신의 포털에 설치할 수 있는 공개 다중 계정 앱이 될 때만 고려하세요.
첫 번째 HubSpot API 호출: Node와 Python에서 연락처 생성
정규 첫 호출은 연락처 생성이며, 공식 SDK를 사용하면 몇 줄입니다. 클라이언트를 설치하고, 환경에서 비공개 앱 토큰으로 초기화한 다음, 연락처를 생성하고 거래를 읽어옵니다. 이것은 회사, 티켓, HubSpot 커스텀 객체 API 호출을 위해 반복할 같은 패턴입니다. 객체 유형만 변합니다.
다음은 @hubspot/api-client(v14)를 사용한 Node 버전입니다:
Python에서 hubspot-api-client(v12)를 사용한 같은 코드입니다:
팁: HubSpot 개발자 샌드박스에 대해 테스트하세요, 프로덕션을 먼저 테스트하지 마세요. 프로덕션에서 잘못 형식화된 생성 호출은 영업 팀이 정리해야 할 실제 쓰레기 레코드를 남깁니다. 토큰, 스코프, 객체 모델은 샌드박스에서도 동일하게 작동합니다.
HubSpot을 내부 도구로 실시간으로 동기화하려면?
폴링이 아닌 웹훅을 사용하세요. 비공개 앱의 웹훅 탭에서 관심 있는 객체와 이벤트에 대한 웹훅 구독을 등록하고(예: deal.propertyChange), 호스팅하는 HTTPS 엔드포인트를 가리키면, HubSpot은 일치하는 변경이 발생하는 즉시 작은 JSON 배열을 POST합니다. 필요한 것을 감시하는 구독이 없을 때만 폴링하세요.
이점은 효율성입니다. 폴링은 매분 "뭔가 새로운 게 있나?"를 묻고 그 과정에서 속도 제한을 소모합니다. 웹훅은 거래가 변경되는 순간 알려줍니다. 그 차이는 규모가 중요하며, 웹훅은 이제 주류입니다. Postman의 2025 API 상태 보고서는 5,700명 이상의 개발자를 대상으로 한 설문조사에서 대략 절반의 팀이 이를 의존한다고 발견했습니다.
비공개 앱의 웹훅 탭에서 구독을 등록하고, 대상 URL을 설정한 다음, 이벤트를 선택하세요. HubSpot은 이벤트 객체의 배열을 보내며, 각각은 subscriptionType, objectId, 그리고 변경된 내용을 전달합니다. Express를 사용한 수신기 스텁은 다음과 같습니다:
여기서 구축이 실제가 됩니다. 작은 제조업체의 ERP 레코드로 거래를 동기화한다고 가정하세요. 웹훅이 발생하고, 핸들러가 일치하는 ERP 티켓을 생성하거나 업데이트하며, ops 팀은 HubSpot에 접근하지 않고도 변경을 볼 수 있습니다. 음성 에이전트를 CRM과 동기화하는 데 사용하는 같은 실시간 접근 방식입니다. 유일한 차이는 트리거가 전화 호출 대신 속성 변경입니다. 한 가지 경고: 위의 스텁은 POST된 모든 것을 신뢰합니다. 라이브로 가기 전에 이를 수정하세요.
웹훅 서명 검증(v3): 위조된 페이로드를 절대 신뢰하지 않기
v3 서명으로 들어오는 모든 웹훅을 검증하세요. HubSpot은 각 요청에 앱 시크릿으로 서명하고 X-HubSpot-Signature-v3과 X-HubSpot-Request-Timestamp 두 헤더를 보냅니다. 5분보다 오래된 것은 거부하고, 메서드 + 전체 URL + 원본 본문 + 타임스탬프로 소스 문자열을 재구성한 다음, 앱 시크릿을 사용하여 HMAC-SHA256으로 계산하고, base64 인코딩한 다음, 상수 시간으로 비교하세요.
이를 건너뛰면, 웹훅 URL을 추측하는 모든 사람이 거래 업데이트를 위조할 수 있습니다. 검증은 선택사항이 아닙니다. HubSpot의 요청 검증 문서와 v3 서명 변경 로그는 정확한 레시피를 제시합니다. Express 미들웨어로 드롭인하면:
Python 함수로도 같은 검사입니다. 두 스택 모두 다룹니다:
사람들을 반나절 낭비하게 하는 함정: HubSpot은 전체 대상 URL(스킴, 호스트, 경로 포함)에 서명합니다. 프록시, 로드 밸런서 또는 ngrok 터널 뒤에서는 req.get("host")이 HubSpot이 서명한 공개 호스트 대신 내부 호스트를 보고할 수 있습니다. 재구성한 정확한 URI를 로깅하고 공개 웹훅 URL과 문자별로 비교하세요. 검증이 계속 실패한다면, 당신이 확신하는 합법적인 페이로드입니다.
속도 제한, 429s, 및 배치 API: 프로덕션에서 실행한 것
...