GoHighLevel API 和 Webhooks：自定义集成

GoHighLevel 的本机集成和 Zapier 连接器涵盖了大多数标准用例，但具有特定工作流程、专有系统或高数据量的企业最终需要直接使用 GHL 的 API。 GHL REST API 和 Webhook 系统使开发人员能够以编程方式完全访问联系人、管道、活动、约会等，从而实现无代码工具无法复制的集成。

本指南是为与 GoHighLevel 构建自定义集成的技术团队编写的。它涵盖了 API 架构、身份验证、关键端点、Webhook 设置和安全性以及常见用例的实用集成模式。

要点

• GHL 的 REST API (v2) 使用 OAuth 2.0 进行身份验证并支持所有主要 CRM 对象
• GHL 工作流程中的入站 webhooks 让外部系统实时触发 GHL 自动化
• 当 GHL 事件发生时（创建联系人、更新管道等），来自 GHL 的出站 Webhook 会通知外部系统
• 速率限制为每个位置 100 个请求/10 秒 — 批量操作和缓存对于规模化非常重要
• GHL Marketplace 允许您将集成发布为 GHL 本机应用程序以供客户安装
• 自定义值和自定义字段是存储集成状态的主要数据扩展点
• 使用 GHL 签名标头进行 Webhook 有效负载验证可防止欺骗请求
• 大多数 GHL 集成遵循四种模式：联系人同步、事件触发自动化、管道桥接或报告聚合

---

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 进行所有身份验证。有两种身份验证上下文：

1.机构级 API 密钥（用于子账户管理）

对于管理多个子账户的服务器到服务器集成，请使用代理 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 端点批量创建联系人（在当前 API 文档中验证您的 GHL 版本）。对于导入超过 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 Pipeline Sync

当在外部系统（例如 Salesforce）中创建交易时，您的集成代码：

1. 通过电子邮件在 GHL 中搜索联系人
2. 如果未找到则创建联系人
3. 创建与联系人关联的 GHL 机会
4. 将 GHL 机会 ID 作为自定义字段存储在 Salesforce 中以进行双向同步

---

入站 Webhooks：从外部系统触发 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 字段可用作工作流程中的变量。

入站 Webhooks 的用例：

• 电子商务订单下 → 触发购买后序列
• 创建支持票 → 添加“主动支持”标签，暂停营销序列
• 收到付款 → 将管道移至“赢得”，触发入职工作流程
• 试用注册 → 启动 SaaS 入门流程
• 在第三方网站上提交表格 → 将潜在客户捕获到 GHL CRM 中

---

出站 Webhook：GHL 通知外部系统

当 GHL 事件发生时，出站 Webhook 将数据从 GHL 发送到外部系统。

在 GHL 中配置出站 Webhook：

导航到 设置 > 集成 > Webhooks（子帐户级别）或在工作流程中添加 Webhook 操作。

GHL 本机出站事件（可在“设置”>“Webhooks”中找到）：

• 已创建联系人
• 联系方式已更新
• 联系方式已删除
• 机会创建/更新/删除
• 已提交表格
• 预约已预订/取消/未出现
• 对话消息（入站）
• 通话开始/结束

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 进行比较 - 字符串相等容易受到计时攻击。

当您在 GHL 设置中创建 Webhook 时，您的 Webhook 密钥已设置。

---

速率限制和最佳实践

GHL 对 API 访问实施速率限制。截至 2026 年，标准限制为每个位置每 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。在 Redis 或数据库中缓存联系人 ID 查找，TTL 为 15 分钟。大多数集成流程重复涉及相同的联系人。

3.批量联系人更新： 如果您要在批量数据处理后更新 500 个联系人的自定义字段，请以 10 个为一组进行批处理更新，批次之间有 100 毫秒的延迟，而不是同时触发所有 500 个联系人。

4.使用 Webhooks 而不是轮询： 切勿轮询 GHL 的 API 进行更改（例如，每分钟检查是否创建了新联系人）。使用 GHL 的出站 Webhook 在事件发生时接收通知。这消除了与轮询相关的速率限制消耗。

---

构建 GHL Marketplace 应用程序

如果您正在为多个 GHL 客户构建集成，请考虑将其发布为 GHL Marketplace 应用程序。这使得 GHL 用户只需单击一下即可安装您的集成，并使用 OAuth 进行身份验证 — 无需手动共享 API 密钥。

市场上市要求：

• OAuth 2.0 实施
• 隐私政策和服务条款 URL
• 应用程序图标和说明
• Webhook 处理您的应用程序订阅的事件
• GHL 审核和批准流程（通常 1-2 周）

市场分销的好处：

• GHL 用户一键安装
• OAuth 处理身份验证（无 API 密钥管理）
• 通过 GHL 市场提高可发现性
• 能够通过 GHL 的计费基础设施对集成进行收费

如果您正在构建多个 GHL 机构或企业将使用的集成，那么这条路径值得采用 - 分销杠杆非常重要。

---

常见集成模式

模式1：电子商务订单同步

• Shopify 订单 Webhook → 您的中间件 → GHL 联系人更新 + 标签 + 工作流程注册
• 中间件验证有效负载、删除重复联系人、将订单数据映射到 GHL 自定义字段

模式 2：ERP 到 CRM 的桥梁

• 创建 ERP（Odoo、QuickBooks）发票 → 连接到中间件的 Webhook → GHL 机会标记为 Won + 管道已移动
• 双向同步：GHL管道变更→ERP订单状态更新

模式3：预约+现场服务同步

• 预订 GHL 预约 → 出站 webhook → FSM 工具创建作业
• FSM 作业已完成 → Webhook 到 GHL → 将管道移至已完成 + 触发审核序列

模式 4：数据仓库报告

• 每日：GHL API 提取前一天的联系人、机会和沟通事件
• 存储在数据仓库中的数据（BigQuery、Snowflake）
• Power BI 或 Looker 连接到数据仓库以进行高级跨平台分析

---

常见问题

GHL v1 和 v2 API 有什么区别？

与 v1 的 API 密钥身份验证相比，GHL 的 v2 API（于 2022 年至 2023 年左右推出）使用 OAuth 2.0 和更简洁的 REST 设计。 v2 API 具有更全面的端点覆盖范围和更好的文档。新的集成应该基于 v2 构建。 GHL 已表示打算弃用 v1，但尚未设定确切的时间表 - 请查看 GHL 的开发人员公告以了解当前状态。

我可以使用 GHL 的 API 以编程方式发送短信吗？

是的。使用 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 系统使其成为一个真正可扩展的平台 - 不仅仅是一个无代码营销工具，而且是一个可以与几乎任何业务系统集成的可编程客户通信引擎。关键是从一开始就构建干净、经过良好测试的集成，并进行适当的错误处理和签名验证。

ECOSIRE 的 GoHighLevel 服务 包括自定义 API 集成开发。我们的技术团队为电子商务平台、ERP 系统、现场服务管理工具和专有业务应用程序构建 GHL 集成。我们设计与适当的错误处理、速率限制管理和监控的集成。

联系我们的团队 讨论您的自定义集成要求并获取您的特定 GHL 集成项目的技术范围。