如何自动检测GHL中客户主域名变更？技术方案咨询

1. 触发主域名更新的Webhook/事件 #

GHL中，当客户的主域名字段（内置或自定义）发生变更时，会触发对应实体的更新事件：

• 若主域名绑定在联系人实体：触发contact.updated事件
• 若主域名绑定在公司实体：触发company.updated事件

配置Webhook时，需在GHL后台指定接收端点并勾选对应更新事件；建议添加字段过滤条件，仅监听主域名字段的变更，减少无效请求触发。

2. 获取当前主域名或追踪变更的API端点 #

• 获取当前主域名：
  • 联系人实体：GET /contacts/{contactId}，返回数据中提取主域名字段（内置字段通常为primaryDomain，自定义字段为你设置的名称）
  • 公司实体：GET /companies/{companyId}，同理可获取主域名值
• 追踪变更历史：
  • 联系人变更记录：GET /contacts/{contactId}/history，筛选fieldUpdated类型记录，匹配主域名字段即可获取变更前后的值
  • 公司变更记录：GET /companies/{companyId}/history，逻辑同上

3. 实现primaryDomainUpdated()函数的最佳实践 #

核心逻辑（Webhook触发式） #

函数负责验证Webhook合法性、检测域名变更、执行业务逻辑，示例代码（JavaScript）：

function primaryDomainUpdated(webhookPayload) {
  // 验证GHL Webhook签名，防止伪造请求
  const isValid = verifyGhlSignature(webhookPayload, process.env.GHL_WEBHOOK_SECRET);
  if (!isValid) return { status: 403, message: "Invalid request signature" };

  // 提取变更前后的域名值（假设主域名是自定义字段`primaryDomain`）
  const { old: oldData, new: newData } = webhookPayload.data;
  const oldDomain = oldData?.primaryDomain;
  const newDomain = newData?.primaryDomain;

  // 过滤非变更场景（首次设置、无变化）
  if (!oldDomain || oldDomain === newDomain) {
    return { status: 200, message: "No valid domain change detected" };
  }

  // 执行业务逻辑（示例：记录日志、同步到内部系统）
  recordDomainChange(webhookPayload.data.id, oldDomain, newDomain);
  syncDomainToInternalSystem(newDomain, webhookPayload.data.id);

  return { status: 200, message: "Domain change processed successfully" };
}

// 辅助函数：GHL Webhook签名验证
function verifyGhlSignature(payload, secret) {
  const signatureHeader = payload.headers["x-ghl-signature"];
  if (!signatureHeader) return false;
  
  const computedSignature = crypto.createHmac("sha256", secret)
    .update(JSON.stringify(payload.body))
    .digest("hex");
  
  return computedSignature === signatureHeader;
}

最佳实践要点 #

• 强制签名验证：必须验证Webhook签名，避免恶意请求
• 幂等处理：通过事件ID或变更记录ID标记已处理请求，防止重复执行
• 错误容错：对业务逻辑中的API调用添加重试机制，处理网络异常
• 日志记录：完整记录变更时间、客户ID、新旧域名，便于后续排查
• 场景区分：区分首次设置域名和域名变更，避免误触发业务流程

4. 官方文档与实现案例 #

• 官方文档：GHL官方文档的Webhook章节详细说明了事件类型、签名验证规则；API章节覆盖了联系人/公司详情、历史记录的端点使用方法
• 常见实现案例：
  • 同步域名变更到CRM系统，更新客户关联的域名信息
  • 触发Slack/Teams通知，提醒运营团队跟进客户域名变更
  • 自动更新网站域名白名单，确保客户新域名能正常访问服务

内容的提问来源于stack exchange，提问作者Jelly Roll