GoHighLevel API と Webhook: カスタム統合

GoHighLevel のネイティブ統合と Zapier コネクタは、ほとんどの標準的なユースケースをカバーしますが、特定のワークフロー、独自のシステム、または大量のデータを扱う企業は、最終的に GHL の API を直接操作する必要があります。 GHL REST API と Webhook システムにより、開発者は連絡先、パイプライン、キャンペーン、予定などにプログラムから完全にアクセスできるようになり、ノーコード ツールでは再現できない統合が可能になります。

このガイドは、GoHighLevel とのカスタム統合を構築する技術チーム向けに書かれています。 API アーキテクチャ、認証、主要なエンドポイント、Webhook のセットアップとセキュリティ、一般的なユースケースの実践的な統合パターンについて説明します。

重要なポイント

• GHL の REST API (v2) は認証に OAuth 2.0 を使用し、すべての主要な CRM オブジェクトをサポートします
• GHL ワークフローのインバウンド Webhook により、外部システムがリアルタイムで GHL 自動化をトリガーできるようになります
• GHL からのアウトバウンド Webhook は、GHL イベントが発生したときに (連絡先の作成、パイプラインの更新など) 外部システムに通知します。
• レート制限は 1 ロケーションあたり 100 リクエスト/10 秒 — バッチ操作とキャッシュは大規模な場合に重要です
• GHL Marketplace を使用すると、統合を GHL ネイティブ アプリとして公開し、顧客がインストールできるようになります。
• カスタム値とカスタム フィールドは、統合状態を保存するための主要なデータ拡張ポイントです
• GHL 署名ヘッダーを使用した Webhook ペイロード検証により、なりすましリクエストを防止します
• ほとんどの GHL 統合は 4 つのパターンに従います: 連絡先の同期、イベントトリガーの自動化、パイプラインブリッジング、またはレポートの集計

---

GHL API アーキテクチャの概要

GoHighLevel の API (2026 年時点ではバージョン 2) は、JSON リクエストおよびレスポンスボディを備えた標準 REST API です。ベース URL は次のとおりです。

https://services.leadconnectorhq.com

API は、リソースを次のプライマリ名前空間に編成します。

完全な API ドキュメントは https://highlevel.stoplight.io/docs/integrations/ で入手できます。

---

認証: OAuth 2.0 セットアップ

GHL の API は、すべての認証に OAuth 2.0 を使用します。 2 つの認証コンテキストがあります。

1.代理店レベルの API キー (サブアカウント管理用)

複数のサブアカウントを管理するサーバー間の統合の場合は、Agency API キーを使用します。

• 代理店設定 > API キーで生成
• 代理店レベルの業務を対象としています (サブアカウントの作成/管理)

2.サブアカウント OAuth (場所ごとの統合用)

単一のサブアカウント内で動作する統合の場合 (最も一般的なケース):

Authorization Flow:
1. Register your app in GHL Marketplace (or use a private integration key)
2. Redirect user to GHL OAuth consent page:
   https://marketplace.gohighlevel.com/oauth/chooselocation?response_type=code
     &redirect_uri=YOUR_CALLBACK_URL
     &client_id=YOUR_CLIENT_ID
     &scope=contacts.readonly+contacts.write+opportunities.write+...
3. User approves → GHL redirects to your callback with ?code=AUTH_CODE
4. Exchange auth code for access + refresh tokens:
   POST https://services.leadconnectorhq.com/oauth/token
   Body: {
     client_id, client_secret, grant_type: "authorization_code",
     code: AUTH_CODE, redirect_uri: YOUR_CALLBACK_URL
   }
5. Use access token in Authorization header: Bearer ACCESS_TOKEN
6. Refresh access token when expired (typically every 24 hours) using refresh token

一般的な操作に必要なスコープ:

必要なスコープのみをリクエストします。スコープを最小限にすることがセキュリティのベスト プラクティスです。

---

コア API オペレーション: 連絡先

連絡先 API は、GHL 統合で最も頻繁に使用されるエンドポイントです。

連絡先の作成または更新:

POST https://services.leadconnectorhq.com/contacts/
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]",
  "phone": "+14155551234",
  "locationId": "YOUR_LOCATION_ID",
  "source": "shopify-integration",
  "tags": ["new-customer", "shopify"],
  "customFields": [
    {
      "id": "CUSTOM_FIELD_ID_FOR_ORDER_COUNT",
      "field_value": "1"
    }
  ]
}

応答 (201 件作成):

{
  "contact": {
    "id": "abc123xyz",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "[email protected]",
    "phone": "+14155551234",
    "locationId": "YOUR_LOCATION_ID",
    "tags": ["new-customer", "shopify"],
    "createdAt": "2026-03-19T10:30:00.000Z"
  }
}

電子メールによる連絡先の検索 (重複排除のため):

GET https://services.leadconnectorhq.com/contacts/search
  ?locationId=YOUR_LOCATION_ID
  &[email protected]
Authorization: Bearer ACCESS_TOKEN

連絡先レコードの重複を避けるために、作成する前に必ず検索してください。

連絡先にタグを追加:

POST https://services.leadconnectorhq.com/contacts/abc123xyz/tags
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "tags": ["vip-customer", "order-placed"]
}

一括操作:

GHL は、POST /contacts/bulk エンドポイントを介した連絡先の一括作成をサポートしています (GHL バージョンの現在の API ドキュメントで確認してください)。 500 を超える連絡先をインポートする場合は、レート制限内に収まるように、リクエストごとに 100 件の連絡先のバッチで一括エンドポイントを使用します。

---

パイプラインとオポチュニティ API

機会を作る:

POST https://services.leadconnectorhq.com/opportunities/
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "pipelineId": "YOUR_PIPELINE_ID",
  "pipelineStageId": "YOUR_STAGE_ID",
  "contactId": "abc123xyz",
  "name": "Jane Smith - HVAC Service",
  "monetaryValue": 450,
  "status": "open",
  "assignedTo": "USER_ID"
}

チャンスを新たなステージへ:

PUT https://services.leadconnectorhq.com/opportunities/OPPORTUNITY_ID
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "pipelineStageId": "NEW_STAGE_ID"
}

一般的な統合パターン: 外部 CRM → GHL パイプライン同期

取引が外部システム (Salesforce など) で作成される場合、統合コードは次のようになります。

1. GHL で連絡先を電子メールで検索します
2. 連絡先が見つからない場合は作成します
3. 連絡先にリンクされた GHL オポチュニティを作成します
4. 双方向同期のために GHL オポチュニティ ID を Salesforce のカスタムフィールドとして保存します

---

インバウンド Webhook: 外部システムから GHL をトリガーする

インバウンド Webhook を使用すると、外部システムが GHL ワークフローを起動できるようになります。これは、イベント駆動型統合の主要なメカニズムです。

GHL でのインバウンド Webhook トリガーの作成:

1. [オートメーション] > [ワークフロー] > [新しいワークフロー] に移動します。
2. トリガーの種類として「Inbound Webhook」を選択します
3. GHL は一意の URL を生成します。 コード0
4. ワークフローが Webhook ペイロードから使用するデータを構成する

受信 Webhook へのデータの送信:

POST https://services.leadconnectorhq.com/hooks/YOUR_UNIQUE_HOOK_ID/webhook-trigger
Content-Type: application/json

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "phone": "+14155559876",
  "customData": {
    "order_id": "ORD-12345",
    "product_name": "AC Tune-Up Service",
    "order_value": "299.00"
  }
}

GHL は、認識するペイロード フィールド (名、姓、電子メール、電話番号) から連絡先を作成または更新し、customData フィールドをワークフロー内の変数として使用できるようにします。

インバウンド Webhook の使用例:

• eコマースの注文 → 購入後のシーケンスをトリガー
• サポート チケットが作成されました → 「アクティブ サポート」タグを追加し、マーケティング シーケンスを一時停止します
• 支払いを受領 → パイプラインを「落札」に移動し、オンボーディング ワークフローをトリガーします
• トライアルサインアップ → SaaS オンボーディングシーケンスを開始
• サードパーティのサイトでフォームを送信 → リードを GHL CRM に取り込む

---

アウトバウンド Webhook: GHL による外部システムへの通知

アウトバウンド Webhook は、GHL イベントが発生したときに GHL から外部システムにデータを送信します。

GHL での送信 Webhook の構成:

[設定] > [統合] > [Webhook] (サブアカウント レベル) に移動するか、ワークフロー内に Webhook アクションを追加します。

GHL ネイティブ アウトバウンド イベント ([設定] > [Webhook] で利用可能):

• 連絡先が作成されました
• 連絡先が更新されました
• 連絡先が削除されました
• 商談の作成/更新/削除
• フォームの送信
• 予約済み/キャンセル/不泊
• 会話メッセージ（インバウンド）
• 通話開始/終了

GHL ワークフロー Webhook アクション:

より詳細に制御するには、ワークフロー内に「Webhook の送信」アクションを追加します。これは、ワークフローがそのステップに到達した場合にのみ起動され、どのイベントが外部システムに通知するか、どのようなペイロードを受信するかを正確に制御できるようになります。

// Example workflow webhook payload to your system
{
  "event": "appointment_booked",
  "contact": {
    "id": "{{contact.id}}",
    "name": "{{contact.full_name}}",
    "email": "{{contact.email}}",
    "phone": "{{contact.phone}}"
  },
  "appointment": {
    "calendar_id": "{{appointment.calendar_id}}",
    "start_time": "{{appointment.start_time}}",
    "service": "{{appointment.title}}"
  },
  "custom_fields": {
    "order_id": "{{contact.order_id}}"
  }
}

GHL のカスタム値構文 ({{variable.path}}) を使用して、動的連絡先およびイベント データをペイロードに含めます。

---

Webhook セキュリティ: 署名検証

GHL は、HMAC-SHA256 署名を使用してアウトバウンド Webhook に署名します。なりすましリクエストを防ぐために、受信エンドポイントはこの署名を検証する必要があります。

検証プロセス:

GHL には、各 Webhook リクエストに署名ヘッダーが含まれています。

X-GHL-Signature: sha256=COMPUTED_HMAC

サーバーは以下を検証します。

const crypto = require('crypto');

function verifyGHLWebhook(payload, signature, secret) {
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload) // raw request body as Buffer
    .digest('hex');

  const expectedSignature = `sha256=${computedSignature}`;

  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(signature)
  );
}

比較には常に crypto.timingSafeEqual を使用します。文字列の等価性はタイミング攻撃に対して脆弱です。

Webhook シークレットは、GHL の設定で Webhook を作成するときに設定されます。

---

レート制限とベストプラクティス

GHL は API アクセスにレート制限を適用します。 2026 年の時点で、標準の制限は、1 つの場所につき 10 秒あたり約 100 リクエストです。これを超えると、429 Too Many Requests 応答が返されます。

レート制限内にとどまるための戦略:

1.指数バックオフの実装:

async function apiCallWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
        await new Promise(r => setTimeout(r, delay));
      } else {
        throw error;
      }
    }
  }
}

2.連絡先検索のキャッシュ: 受信イベントごとに電子メールで GHL を検索しないでください。連絡先 ID の検索を Redis またはデータベースに 15 分の TTL でキャッシュします。ほとんどの統合フローには、同じ連絡先が繰り返し含まれます。

3.連絡先の一括更新: 一括データ処理後に 500 件の連絡先のカスタム フィールドを更新する場合は、500 件すべてを同時に実行するのではなく、バッチ間に 100 ミリ秒の遅延を設けて 10 件のグループに分けて更新をバッチ処理します。

4.ポーリングの代わりに Webhook を使用する: 変更について GHL の API を決してポーリングしないでください (新しい連絡先が作成されたかどうかを毎分確認するなど)。 GHL のアウトバウンド Webhook を使用して、イベントが発生したときに通知を受け取ります。これにより、ポーリング関連のレート制限の消費がなくなります。

---

GHL マーケットプレイス アプリの構築

複数の GHL 顧客向けの統合を構築している場合は、それを GHL Marketplace アプリとして公開することを検討してください。これにより、GHL ユーザーは認証に OAuth を使用してワンクリックで統合をインストールできるようになり、手動で API キーを共有する必要はありません。

マーケットプレイス出品の要件:

• OAuth 2.0の実装
• プライバシーポリシーと利用規約のURL
• アプリのアイコンと説明
• アプリがサブスクライブするイベントの Webhook 処理
• GHL のレビューおよび承認プロセス (通常は 1 ～ 2 週間)

マーケットプレイス配布の利点:

• GHL ユーザー向けのワンクリックインストール
• OAuth が認証を処理します (API キー管理なし)
• GHL のマーケットプレイスによる発見可能性の向上
• GHL の課金インフラストラクチャを介して統合に料金を請求する機能

複数の GHL 代理店または企業が使用する統合を構築している場合、この方法は追求する価値があります。配布の活用は重要です。

---

一般的な統合パターン

パターン 1: e コマース注文の同期

• Shopify 注文 Webhook → ミドルウェア → GHL 連絡先更新 + タグ + ワークフロー登録
• ミドルウェアはペイロードを検証し、連絡先の重複を排除し、注文データを GHL カスタム フィールドにマッピングします

パターン 2: ERP から CRM へのブリッジ

• ERP (Odoo、QuickBooks) の請求書が作成されました → ミドルウェアへの Webhook → GHL 案件が落札とマーク + パイプラインが移動
• 双方向同期: GHL パイプライン変更 → ERP 注文ステータス更新

パターン 3: 予約 + フィールド サービスの同期

• GHL 予約の予約 → アウトバウンド Webhook → FSM ツールによるジョブの作成
• FSM ジョブが完了 → GHL への Webhook → パイプラインを完了に移動 + レビュー シーケンスをトリガー

パターン 4: データ ウェアハウスのレポート作成

• 毎日: GHL API は前日の連絡先、商談、コミュニケーション イベントを取得します
• データ ウェアハウスに保存されたデータ (BigQuery、Snowflake)
• Power BI または Looker は、高度なクロスプラットフォーム分析のためにデータ ウェアハウスに接続します

---

よくある質問

GHL の v1 API と v2 API の違いは何ですか?

GHL の v2 API (2022 ～ 2023 年頃に導入) は、OAuth 2.0 と、v1 の API キー認証と比較してよりクリーンな REST 設計を使用します。 v2 API には、より包括的なエンドポイントが含まれており、ドキュメントも充実しています。新しい統合は v2 上に構築する必要があります。 GHL は v1 を非推奨にする意向を表明していますが、まだ明確なスケジュールを設定していません。現在の状況については、GHL の開発者向け発表を確認してください。

GHL の API を使用してプログラムで SMS メッセージを送信できますか?

はい。 POST /conversations/messages エンドポイントを使用して、連絡先に SMS メッセージを送信します。会話 ID (POST /conversations/ によって作成) と連絡先の電話番号が必要です。送信する前に連絡先が SMS オプトイン ステータスであることを確認します。GHL はこれを強制するため、オプトアウトされた連絡先への送信は失敗します。必須の type: "SMS" パラメータと GHL ロケーションの Twilio 番号を送信者として含めます。

大規模なデータセットの GHL API ページネーションを処理するにはどうすればよいですか?

GHL のリスト エンドポイントは、ページ分割された結果を返します。応答には、total、currentPage、nextPage (またはカーソルベースの startAfterId) を含む meta オブジェクトが含まれます。 nextPage が null になるか、すべてのレコードを収集するまでページを反復してページネーションを実装します。大規模な連絡先エクスポート (100,000 件以上の連絡先) の場合は、GHL の一括エクスポート機能を使用するか、GHL サポートに連絡してデータ エクスポートをリクエストしてください。非常に大規模なデータセットの API によるページネーションは時間がかかり、レート制限がかかります。

GHL API 統合をテストするためのサンドボックス環境はありますか?

GHL には専用のサンドボックス環境がありません。テストには別の GHL トライアル アカウントまたは開発サブアカウントを使用してください。テストデータと実際の連絡先を区別するために、明確にラベル付けされた電子メール (例: [email protected]) を使用してテスト連絡先を作成します。テスト データを定期的にクリーンアップして、開発アカウントを整理した状態に保ちます。

外部システムに GHL 連絡先 ID を保存する最良の方法は何ですか?

GHL contact.id (一意の文字列) を外部システムのカスタム フィールドとして保存します (データベースの ghl_contact_id 列など)。これにより、検索ステップを行わずに、正しい連絡先への直接 API 呼び出しが可能になります。 GHL で連絡先を作成する場合は、返された ID をすぐに保存します。双方向同期の場合は、逆引き参照用にシステムの一意の ID を GHL カスタム フィールド (例: external_user_id) として保存します。

---

次のステップ

GoHighLevel の API と Webhook システムにより、GoHighLevel は真に拡張可能なプラットフォームになり、単なるコード不要のマーケティング ツールではなく、事実上あらゆるビジネス システムと統合できるプログラム可能な顧客コミュニケーション エンジンとなります。重要なのは、最初から適切なエラー処理と署名検証を備えたクリーンで十分にテストされた統合を構築することです。

ECOSIRE の GoHighLevel サービス には、カスタム API 統合開発が含まれます。当社の技術チームは、e コマース プラットフォーム、ERP システム、フィールド サービス管理ツール、独自のビジネス アプリケーションのための GHL 統合を構築します。適切なエラー処理、レート制限管理、監視を備えた統合を設計します。

チームにお問い合わせください して、カスタム統合要件について話し合い、特定の GHL 統合プロジェクトの技術範囲を取得します。