HubSpot API & Webhook開発ガイド｜カスタム連携の設計パターン

「HubSpotの標準連携やiPaaSでは実現できないカスタム連携が必要になった」「自社の基幹システムとHubSpotをリアルタイムで同期させたい」——ノーコード連携の限界を感じた企業が次に検討するのが、API & Webhookによるカスタム連携開発です。

HubSpot API & Webhook開発とは、HubSpotが提供するREST APIとWebhookを活用して、自社システムや外部サービスとのカスタム連携を構築する開発手法です。コンタクト・取引・チケットなどのCRMオブジェクトの操作から、カスタムイベントのリアルタイム検知まで、標準機能では実現できない高度な連携を実装できます。

本記事では、HubSpot APIの基本構造、Webhookの仕組み、主要な連携パターン、セキュリティ設計のポイントを解説します。

この記事でわかること

• HubSpot APIの基本構造とエンドポイント
• Webhookの仕組みとイベント検知の設計
• 主要なカスタム連携パターン5選
• API認証方式の選び方
• セキュリティとレート制限への対応

HubSpot APIの基本構造

APIの種類

HubSpotは包括的なREST APIを提供しており、CRMのほぼすべてのデータにプログラムからアクセスできます。

認証方式

自社システムとの連携であれば、プライベートアプリトークンが最もシンプルで推奨されます。「設定」→「連携」→「プライベートアプリ」から作成でき、必要なスコープ（権限）を個別に設定できます。

ここが結構ミソになってくるのですが、スコープの設定は必要最小限にすることが重要です。「ユーザーは管理者のみ変更できるようにする」——この権限管理の考え方はAPIアクセスにも適用すべきです。

Webhookの仕組みと設計

Webhookとは

Webhookは、HubSpot内で特定のイベント（コンタクト作成、取引ステージ変更など）が発生した際に、指定したURLに自動的にHTTPリクエストを送信する仕組みです。ポーリング（定期的なAPI問い合わせ）と異なり、イベント発生時にリアルタイムでデータを受信できます。

Webhookで検知できるイベント

• コンタクトの作成・更新・削除
• 取引の作成・ステージ変更・削除
• 会社の作成・更新
• チケットの作成・ステージ変更
• フォームの送信
• メールの開封・クリック

Webhookの設定方法

方法1: ワークフローのWebhookアクション

HubSpotのワークフローに「Webhookを送信」アクションを追加し、任意のURLにデータをPOSTできます。ワークフローの条件分岐と組み合わせることで、特定の条件を満たした場合のみWebhookを発火させられます。

方法2: HubSpotアプリのWebhookサブスクリプション

プライベートアプリまたは公開アプリの設定で、Webhookサブスクリプションを作成し、特定のイベントを監視できます。

主要な連携パターン5選

パターン1: 基幹システムとの双方向同期

HubSpotで受注した取引データを自社の基幹システム（ERP）に自動連携し、請求・出荷プロセスを開始するパターンです。

設計のポイント:

• 取引のステージ変更をWebhookで検知
• 基幹システム側のAPIを呼び出してデータを登録
• 処理結果をHubSpotのタイムラインにメモとして記録

「HubSpotを1個の業務アプリケーションとして、会計までつながるので販売管理システムのような形で使っていただくこともできる」——この思想をAPI連携で実現するパターンです。

パターン2: カスタムリードスコアリング

HubSpot標準のリードスコアリングでは実現できない、自社独自のスコアリングロジックをAPI経由で実装するパターンです。外部のデータソース（業界DB、企業情報DB等）を参照して、より精密なスコアリングを実現します。

パターン3: カスタムレポート・ダッシュボード

HubSpotのデータをAPIで取得し、BIツール（Tableau、Looker Studio等）に連携してカスタムレポートを作成するパターンです。HubSpotの標準レポートでは表現できない、複雑な分析やクロスプラットフォームのデータ統合が可能になります。

パターン4: ワークフローのカスタムコードアクション

HubSpotのワークフロー内でNode.jsまたはPythonのコードを実行し、外部APIの呼び出しやデータ変換を行うパターンです。iPaaSを使わずに、HubSpotのワークフロー内で外部連携を完結させられます。

「取引が請求書発行ステージに移行したら、カスタムコード（Node.js/Python）で12ヶ月分の請求レコードを自動分割作成する」——こうした複雑な処理もカスタムコードアクションで実現できます。

パターン5: カスタムオブジェクトの活用

HubSpot標準のオブジェクト（コンタクト・会社・取引・チケット）では管理できないデータを、カスタムオブジェクトとしてAPIで作成・管理するパターンです。不動産の物件データ、SaaSのライセンス情報など、業種固有のデータをCRMに統合できます。

セキュリティ設計のポイント

APIトークンの管理

• 環境変数で管理し、ソースコードにハードコーディングしない
• 定期的にトークンをローテーション（更新）する
• 不要になったアプリは速やかに削除する

レート制限への対応

HubSpotのAPIには以下のレート制限があります。

大量データの処理時はバッチAPIを活用し、レート制限に達した場合はリトライロジック（エクスポネンシャルバックオフ）を実装しましょう。

Webhookの検証

Webhookリクエストが本当にHubSpotから送信されたものかを検証するため、リクエストヘッダの署名検証を必ず実装しましょう。

注意点と正直な限界

API開発の現実的なコスト

API連携の開発には、エンジニアリングリソースと保守コストが発生します。「一部システムで解決できない部分は運用面で解決するとか、そういった検討は必要になってくる」——すべてをAPI連携で解決しようとせず、費用対効果を見極めた上で開発範囲を決定しましょう。

APIの後方互換性

HubSpotのAPIはバージョンアップにより仕様が変更される場合があります。v1、v2、v3と複数のバージョンが混在しているエンドポイントもあるため、常に最新のドキュメントを参照しましょう。

まとめ

HubSpot API & Webhook開発により、標準連携やiPaaSでは実現できない高度なカスタム連携を構築できます。まずはプライベートアプリトークンを作成し、小さな読み取り処理から始めてみましょう。

ノーコード連携で対応できる部分はノーコードで、コード連携が必要な部分のみAPIを使う、というハイブリッドアプローチが最も効率的です。段階的に連携の範囲を広げていきましょう。

無料相談はこちら → StartLink お問い合わせ

よくある質問（FAQ）

Q1. HubSpot API開発にはどのプログラミング言語が適していますか？

HubSpotのAPIはREST APIなので、あらゆるプログラミング言語から利用可能です。公式SDKはNode.js、Python、Ruby、PHPで提供されており、特にNode.jsとPythonは情報量が多くおすすめです。HubSpotのカスタムコードアクションもNode.jsとPythonに対応しています。

Q2. APIの利用に追加料金はかかりますか？

HubSpotのAPIは、利用しているプランの範囲内で追加料金なしで利用可能です。ただし、APIでアクセスできるデータの範囲はプランによって異なります。カスタムオブジェクトの作成にはEnterpriseプランが必要です。

Q3. Webhook経由のデータ送信でデータが欠損するリスクはありますか？

ネットワークの一時的な障害などにより、Webhookリクエストが失敗する可能性はあります。HubSpotは失敗したWebhookリクエストをリトライしますが、完全性を保証するものではありません。重要なデータ連携では、定期的なバッチ同期を補完的に実装することをおすすめします。

Q4. HubSpotのサンドボックス環境でAPI開発のテストはできますか？

はい、EnterpriseプランのサンドボックスではAPI開発のテストが可能です。本番データに影響を与えずに開発・テストを行えるため、API連携の開発時はサンドボックスの活用をおすすめします。

Q5. APIとiPaaSはどちらを選ぶべきですか？

連携の複雑さ、処理件数、社内の技術リソースで判断します。シンプルな連携や処理件数が少ない場合はiPaaSが効率的です。複雑なビジネスロジック、大量データの処理、リアルタイム性が求められる場合はAPI開発を選びましょう。