API GoHighLevel e Webhooks: integrações personalizadas

As integrações nativas do GoHighLevel e os conectores Zapier cobrem a maioria dos casos de uso padrão, mas empresas com fluxos de trabalho específicos, sistemas proprietários ou grandes volumes de dados eventualmente precisam trabalhar diretamente com a API da GHL. A API REST da GHL e o sistema de webhook oferecem aos desenvolvedores acesso programático completo a contatos, pipelines, campanhas, compromissos e muito mais, permitindo integrações que ferramentas sem código simplesmente não conseguem replicar.

Este guia foi escrito para equipes técnicas que criam integrações personalizadas com GoHighLevel. Ele cobre a arquitetura da API, autenticação, principais endpoints, configuração e segurança do webhook e padrões práticos de integração para casos de uso comuns.

Principais conclusões

• A API REST (v2) da GHL usa OAuth 2.0 para autenticação e suporta todos os principais objetos de CRM
• Webhooks de entrada em fluxos de trabalho GHL permitem que sistemas externos acionem automações GHL em tempo real
• Webhooks de saída do GHL notificam sistemas externos quando ocorrem eventos GHL (contato criado, pipeline atualizado, etc.)
• Os limites de taxa são 100 solicitações/10 segundos por local — operações em lote e armazenamento em cache são importantes em escala
• O GHL Marketplace permite publicar integrações como aplicativos nativos da GHL para instalação do cliente
• Valores personalizados e campos personalizados são os principais pontos de extensão de dados para armazenar o estado de integração
• A verificação de carga útil do webhook usando o cabeçalho de assinatura GHL evita solicitações falsificadas
• A maioria das integrações GHL segue quatro padrões: sincronização de contatos, automação acionada por eventos, ponte de pipeline ou agregação de relatórios

---

Visão geral da arquitetura da API GHL

A API do GoHighLevel (versão 2 em 2026) é uma API REST padrão com solicitação JSON e corpos de resposta. O URL base é:

https://services.leadconnectorhq.com

A API organiza os recursos nestes namespaces primários:

A documentação completa da API está disponível em https://highlevel.stoplight.io/docs/integrations/.

---

Autenticação: configuração do OAuth 2.0

A API da GHL usa OAuth 2.0 para todas as autenticações. Existem dois contextos de autenticação:

1. Chave de API em nível de agência (para gerenciamento de subcontas)

Para integrações servidor a servidor que gerenciam várias subcontas, use a chave de API da agência:

• Gerado em Configurações da agência > Chaves de API
• Com escopo para operações em nível de agência (criação/gerenciamento de subcontas)

2. OAuth de subconta (para integrações por local)

Para integrações operando em uma única subconta (caso mais comum):

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

Escopos necessários para operações comuns:

Solicite apenas os escopos necessários — o escopo mínimo é uma prática recomendada de segurança.

---

Operações principais da API: contatos

A API de contatos é o endpoint usado com mais frequência nas integrações GHL.

Criar ou atualizar um contato:

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"
    }
  ]
}

Resposta (criada em 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"
  }
}

Pesquise um contato por e-mail (para desduplicação):

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

Sempre pesquise antes de criar para evitar registros de contato duplicados.

Adicionar uma tag a um contato:

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

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

Operações em massa:

GHL oferece suporte à criação de contatos em massa por meio do endpoint POST /contacts/bulk (verifique na documentação atual da API para sua versão GHL). Para importações de mais de 500 contatos, use o endpoint em massa com lotes de 100 contatos por solicitação para permanecer dentro dos limites de taxa.

---

API de pipeline e oportunidade

Crie uma oportunidade:

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"
}

Mova a oportunidade para um novo estágio:

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

{
  "pipelineStageId": "NEW_STAGE_ID"
}

Padrão de integração comum: CRM externo → GHL Pipeline Sync

Quando um negócio é criado em um sistema externo (por exemplo, Salesforce), seu código de integração:

1. Procura o contato no GHL por e-mail
2. Cria o contato se não for encontrado
3. Cria uma oportunidade GHL vinculada ao contato
4. Armazena o ID da oportunidade GHL como um campo personalizado no Salesforce para sincronização bidirecional

---

Webhooks de entrada: acionando GHL de sistemas externos

Os webhooks de entrada permitem que sistemas externos acionem fluxos de trabalho GHL. Este é o principal mecanismo para integração orientada a eventos.

Criando um gatilho de webhook de entrada no GHL:

1. Navegue até Automação > Fluxos de trabalho > Novo fluxo de trabalho
2. Selecione "Inbound Webhook" como tipo de gatilho
3. GHL gera uma URL única: CÓDIGO0
4. Configure quais dados o fluxo de trabalho usa da carga útil do webhook

Enviando dados para o webhook de entrada:

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 cria ou atualiza um contato a partir dos campos de carga que reconhece (nome, sobrenome, email, telefone) e disponibiliza os campos customData como variáveis ​​no fluxo de trabalho.

Casos de uso para webhooks de entrada:

• pedido de comércio eletrônico feito → acionar sequência pós-compra
• Ticket de suporte criado → adicionar tag "active-support", pausar sequências de marketing
• Pagamento recebido → mover o pipeline para "Ganhou", acionar o fluxo de trabalho de integração
• Inscrição de teste → iniciar sequência de integração de SaaS
• Formulário enviado em site de terceiros → capturar lead no GHL CRM

---

Webhooks de saída: GHL notificando sistemas externos

Webhooks de saída enviam dados do GHL para sistemas externos quando ocorrem eventos GHL.

Configurando Webhooks de saída no GHL:

Navegue até Configurações > Integrações > Webhooks (nível de subconta) ou adicione uma ação de webhook dentro de um fluxo de trabalho.

Eventos de saída nativos GHL (disponíveis em Configurações > Webhooks):

• Contato criado
• Contato atualizado
• Contato excluído
• Oportunidade criada/atualizada/excluída
• Formulário enviado
• Consulta marcada/cancelada/não comparecimento
• Mensagem de conversa (entrada)
• Chamada iniciada/terminada

Ação do webhook do fluxo de trabalho GHL:

Para um controle mais granular, adicione uma ação "Enviar Webhook" dentro de um fluxo de trabalho. Isso é acionado somente quando o fluxo de trabalho atinge essa etapa, permitindo controlar exatamente quais eventos notificam sistemas externos e qual carga útil eles recebem.

// 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}}"
  }
}

Use a sintaxe de valor personalizado do GHL ({{variable.path}}) para incluir dados dinâmicos de contato e evento na carga útil.

---

Segurança do Webhook: verificação de assinatura

GHL assina webhooks de saída com uma assinatura HMAC-SHA256. Seu endpoint de recebimento deve verificar essa assinatura para evitar solicitações falsificadas.

Processo de verificação:

GHL inclui um cabeçalho de assinatura com cada solicitação de webhook:

X-GHL-Signature: sha256=COMPUTED_HMAC

Seu servidor verifica:

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)
  );
}

Sempre use crypto.timingSafeEqual para comparação — a igualdade de strings é vulnerável a ataques de temporização.

O segredo do seu webhook é definido quando você cria o webhook nas configurações do GHL.

---

Limitação de taxa e práticas recomendadas

A GHL impõe limites de taxa de acesso à API. A partir de 2026, o limite padrão é de aproximadamente 100 solicitações a cada 10 segundos por local. Exceder isso retorna uma resposta 429 Too Many Requests.

Estratégias para permanecer dentro dos limites de taxas:

1. Implementar espera exponencial:

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. Pesquisas de contato em cache: Não pesquise GHL por e-mail em todos os eventos recebidos. Armazene pesquisas de ID de contato em cache no Redis ou em seu banco de dados com um TTL de 15 minutos. A maioria dos fluxos de integração envolve repetidamente os mesmos contatos.

3. Atualizações de contato em lote: Se você estiver atualizando campos personalizados para 500 contatos após um processo de dados em massa, agrupe as atualizações em grupos de 10 com um atraso de 100 ms entre os lotes, em vez de disparar todos os 500 simultaneamente.

4. Use Webhooks em vez de pesquisas: Nunca pesquise mudanças na API da GHL (por exemplo, verificando a cada minuto se novos contatos foram criados). Use os webhooks de saída do GHL para receber notificações quando ocorrerem eventos. Isso elimina o consumo de limite de taxa relacionado à pesquisa.

---

Construindo um aplicativo GHL Marketplace

Se você estiver criando uma integração para vários clientes GHL, considere publicá-la como um aplicativo GHL Marketplace. Isso permite que os usuários do GHL instalem sua integração com um único clique, usando OAuth para autenticação – sem necessidade de compartilhamento manual de chave de API.

Requisitos para listagem no Marketplace:

• Implementação OAuth 2.0
• Política de privacidade e URLs de termos de serviço
• Ícone e descrição do aplicativo
• Manipulação de webhook para os eventos que seu aplicativo assina
• Processo de revisão e aprovação do GHL (normalmente de 1 a 2 semanas)

Benefícios da distribuição no Marketplace:

• Instalação com um clique para usuários GHL
• OAuth lida com autenticação (sem gerenciamento de chaves de API)
• Maior capacidade de descoberta através do mercado da GHL
• Capacidade de cobrar pela integração através da infraestrutura de cobrança da GHL

Vale a pena seguir esse caminho se você estiver construindo uma integração que várias agências ou empresas da GHL usariam — a alavancagem da distribuição é significativa.

---

Padrões de integração comuns

Padrão 1: sincronização de pedidos de comércio eletrônico

• Webhook de pedido do Shopify → seu middleware → atualização de contato GHL + tag + inscrição no fluxo de trabalho
• Middleware valida carga útil, desduplica contatos, mapeia dados de pedidos para campos personalizados GHL

Padrão 2: Ponte ERP para CRM

• Fatura ERP (Odoo, QuickBooks) criada → webhook para middleware → oportunidade GHL marcada como ganha + pipeline movido
• Sincronização bidirecional: alteração do pipeline GHL → atualização do status do pedido ERP

Padrão 3: Agendamento + Sincronização do Field Service

• Consulta GHL agendada → webhook de saída → ferramenta FSM cria emprego
• Trabalho FSM concluído → webhook para GHL → mover pipeline para Concluído + sequência de revisão do acionador

Padrão 4: Relatórios de data warehouse

• Diariamente: API GHL extrai contatos, oportunidades e eventos de comunicação do dia anterior
• Dados armazenados em seu data warehouse (BigQuery, Snowflake)
• Power BI ou Looker se conecta ao data warehouse para análises avançadas de plataforma cruzada

---

Perguntas frequentes

Qual é a diferença entre as APIs v1 e v2 da GHL?

A API v2 do GHL (introduzida por volta de 2022–2023) usa OAuth 2.0 e um design REST mais limpo em comparação com a autenticação de chave de API v1. A API v2 tem cobertura de endpoint mais abrangente e melhor documentação. Novas integrações devem ser construídas na v2. A GHL declarou a intenção de descontinuar a v1, mas ainda não definiu um cronograma firme – verifique os anúncios dos desenvolvedores da GHL para saber o status atual.

Posso usar a API do GHL para enviar mensagens SMS programaticamente?

Sim. Use o endpoint POST /conversations/messages para enviar mensagens SMS para um contato. Você precisa do ID da conversa (criado por POST /conversations/) e do número de telefone do contato. Certifique-se de que o contato tenha status de aceitação de SMS antes de enviar – a GHL impõe isso e o envio para contatos que optaram por não receber falhará. Inclua o parâmetro type: "SMS" obrigatório e o número Twilio da sua localização GHL como remetente.

Como lidar com a paginação da API GHL para grandes conjuntos de dados?

Os endpoints da lista do GHL retornam resultados paginados. A resposta inclui um objeto meta com total, currentPage e nextPage (ou startAfterId baseado em cursor). Implemente a paginação iterando pelas páginas até que nextPage seja nulo ou você tenha coletado todos os registros. Para exportações de contatos grandes (mais de 100.000 contatos), use o recurso de exportação em massa da GHL ou entre em contato com o suporte da GHL para solicitar uma exportação de dados. A paginação por meio da API para conjuntos de dados muito grandes é lenta e exige muitos limites de taxa.

Existe um ambiente sandbox para testar integrações da API GHL?

GHL não possui um ambiente sandbox dedicado. Use uma conta de teste GHL separada ou uma subconta de desenvolvimento para testes. Crie contatos de teste com e-mails claramente identificados (por exemplo, teste+integraçã[email protected]) para distinguir dados de teste de contatos reais. Limpe os dados de teste regularmente para manter sua conta de desenvolvimento organizada.

Qual é a melhor maneira de armazenar IDs de contato GHL em meu sistema externo?

Armazene o GHL contact.id (uma string exclusiva) como um campo personalizado em seu sistema externo (por exemplo, uma coluna ghl_contact_id em seu banco de dados). Isso permite chamadas diretas de API para o contato correto sem uma etapa de pesquisa. Ao criar contatos no GHL, armazene imediatamente o ID retornado. Para sincronização bidirecional, armazene também o ID exclusivo do seu sistema como um campo personalizado GHL (por exemplo, external_user_id) para a pesquisa inversa.

---

Próximas etapas

A API e o sistema webhook do GoHighLevel o tornam uma plataforma genuinamente extensível – não apenas uma ferramenta de marketing sem código, mas um mecanismo programável de comunicação com o cliente que pode ser integrado a praticamente qualquer sistema de negócios. O segredo é construir integrações limpas e bem testadas, com tratamento adequado de erros e verificação de assinatura desde o início.

Os serviços GoHighLevel da ECOSIRE incluem desenvolvimento de integração de API personalizada. Nossa equipe técnica cria integrações GHL para plataformas de comércio eletrônico, sistemas ERP, ferramentas de gerenciamento de serviços de campo e aplicativos comerciais proprietários. Projetamos integrações com tratamento adequado de erros, gerenciamento de limite de taxa e monitoramento.

Entre em contato com nossa equipe para discutir seus requisitos de integração personalizados e obter um escopo técnico para seu projeto de integração GHL específico.