「HubSpotの標準連携やiPaaSでは実現できないカスタム連携が必要になった」「自社の基幹システムとHubSpotをリアルタイムで同期させたい」——ノーコード連携の限界を感じた企業が次に検討するのが、API & Webhookによるカスタム連携開発です。
HubSpot API & Webhook開発とは、HubSpotが提供するREST APIとWebhookを活用して、自社システムや外部サービスとのカスタム連携を構築する開発手法です。コンタクト・取引・チケットなどのCRMオブジェクトの操作から、カスタムイベントのリアルタイム検知まで、標準機能では実現できない高度な連携を実装できます。
本記事では、HubSpot APIの基本構造、Webhookの仕組み、主要な連携パターン、セキュリティ設計のポイントを解説します。
HubSpotは包括的なREST APIを提供しており、CRMのほぼすべてのデータにプログラムからアクセスできます。
| API カテゴリ | 主要なエンドポイント | 用途 |
|---|---|---|
| CRM API | /crm/v3/objects/contacts, deals, companies | コンタクト・取引・会社の CRUD |
| CMS API | /cms/v3/blogs/posts | ブログ記事の管理 |
| Marketing API | /marketing/v3/forms | フォーム・メール配信 |
| Conversations API | /conversations/v3 | 受信トレイ・チャット管理 |
| Automation API | /automation/v4/actions | ワークフロー・カスタムアクション |
| 認証方式 | 用途 | 推奨シーン |
|---|---|---|
| プライベートアプリトークン | 自社システム連携 | 社内ツールとの連携。最も一般的 |
| OAuth 2.0 | 第三者向けアプリ開発 | HubSpot App Marketplaceへの公開 |
| 開発者APIキー | 開発・テスト用 | 開発環境でのテスト |
自社システムとの連携であれば、プライベートアプリトークンが最もシンプルで推奨されます。「設定」→「連携」→「プライベートアプリ」から作成でき、必要なスコープ（権限）を個別に設定できます。
ここが結構ミソになってくるのですが、スコープの設定は必要最小限にすることが重要です。「ユーザーは管理者のみ変更できるようにする」——この権限管理の考え方はAPIアクセスにも適用すべきです。
Webhookは、HubSpot内で特定のイベント（コンタクト作成、取引ステージ変更など）が発生した際に、指定したURLに自動的にHTTPリクエストを送信する仕組みです。ポーリング（定期的なAPI問い合わせ）と異なり、イベント発生時にリアルタイムでデータを受信できます。
方法1: ワークフローのWebhookアクション
HubSpotのワークフローに「Webhookを送信」アクションを追加し、任意のURLにデータをPOSTできます。ワークフローの条件分岐と組み合わせることで、特定の条件を満たした場合のみWebhookを発火させられます。
方法2: HubSpotアプリのWebhookサブスクリプション
プライベートアプリまたは公開アプリの設定で、Webhookサブスクリプションを作成し、特定のイベントを監視できます。
HubSpotで受注した取引データを自社の基幹システム（ERP）に自動連携し、請求・出荷プロセスを開始するパターンです。
設計のポイント:
「HubSpotを1個の業務アプリケーションとして、会計までつながるので販売管理システムのような形で使っていただくこともできる」——この思想をAPI連携で実現するパターンです。
HubSpot標準のリードスコアリングでは実現できない、自社独自のスコアリングロジックをAPI経由で実装するパターンです。外部のデータソース（業界DB、企業情報DB等）を参照して、より精密なスコアリングを実現します。
HubSpotのデータをAPIで取得し、BIツール（Tableau、Looker Studio等）に連携してカスタムレポートを作成するパターンです。HubSpotの標準レポートでは表現できない、複雑な分析やクロスプラットフォームのデータ統合が可能になります。
HubSpotのワークフロー内でNode.jsまたはPythonのコードを実行し、外部APIの呼び出しやデータ変換を行うパターンです。iPaaSを使わずに、HubSpotのワークフロー内で外部連携を完結させられます。
「取引が請求書発行ステージに移行したら、カスタムコード（Node.js/Python）で12ヶ月分の請求レコードを自動分割作成する」——こうした複雑な処理もカスタムコードアクションで実現できます。
HubSpot標準のオブジェクト（コンタクト・会社・取引・チケット）では管理できないデータを、カスタムオブジェクトとしてAPIで作成・管理するパターンです。不動産の物件データ、SaaSのライセンス情報など、業種固有のデータをCRMに統合できます。
HubSpotのAPIには以下のレート制限があります。
| 制限種類 | 上限 |
|---|---|
| プライベートアプリ | 秒間100リクエスト |
| OAuth アプリ | 秒間100リクエスト |
| バッチAPI | 1回のリクエストで最大100レコード |
大量データの処理時はバッチAPIを活用し、レート制限に達した場合はリトライロジック（エクスポネンシャルバックオフ）を実装しましょう。
Webhookリクエストが本当にHubSpotから送信されたものかを検証するため、リクエストヘッダの署名検証を必ず実装しましょう。
API連携の開発には、エンジニアリングリソースと保守コストが発生します。「一部システムで解決できない部分は運用面で解決するとか、そういった検討は必要になってくる」——すべてをAPI連携で解決しようとせず、費用対効果を見極めた上で開発範囲を決定しましょう。
HubSpotのAPIはバージョンアップにより仕様が変更される場合があります。v1、v2、v3と複数のバージョンが混在しているエンドポイントもあるため、常に最新のドキュメントを参照しましょう。
HubSpot API & Webhook開発により、標準連携やiPaaSでは実現できない高度なカスタム連携を構築できます。まずはプライベートアプリトークンを作成し、小さな読み取り処理から始めてみましょう。
ノーコード連携で対応できる部分はノーコードで、コード連携が必要な部分のみAPIを使う、というハイブリッドアプローチが最も効率的です。段階的に連携の範囲を広げていきましょう。
HubSpotのAPIはREST APIなので、あらゆるプログラミング言語から利用可能です。公式SDKはNode.js、Python、Ruby、PHPで提供されており、特にNode.jsとPythonは情報量が多くおすすめです。HubSpotのカスタムコードアクションもNode.jsとPythonに対応しています。
HubSpotのAPIは、利用しているプランの範囲内で追加料金なしで利用可能です。ただし、APIでアクセスできるデータの範囲はプランによって異なります。カスタムオブジェクトの作成にはEnterpriseプランが必要です。
ネットワークの一時的な障害などにより、Webhookリクエストが失敗する可能性はあります。HubSpotは失敗したWebhookリクエストをリトライしますが、完全性を保証するものではありません。重要なデータ連携では、定期的なバッチ同期を補完的に実装することをおすすめします。
はい、EnterpriseプランのサンドボックスではAPI開発のテストが可能です。本番データに影響を与えずに開発・テストを行えるため、API連携の開発時はサンドボックスの活用をおすすめします。
連携の複雑さ、処理件数、社内の技術リソースで判断します。シンプルな連携や処理件数が少ない場合はiPaaSが効率的です。複雑なビジネスロジック、大量データの処理、リアルタイム性が求められる場合はAPI開発を選びましょう。