GoHighLevel API y Webhooks: integraciones personalizadas

Las integraciones nativas de GoHighLevel y los conectores Zapier cubren la mayoría de los casos de uso estándar, pero las empresas con flujos de trabajo específicos, sistemas propietarios o grandes volúmenes de datos eventualmente necesitan trabajar directamente con la API de GHL. La API REST de GHL y el sistema webhook brindan a los desarrolladores acceso programático completo a contactos, canalizaciones, campañas, citas y más, lo que permite integraciones que las herramientas sin código simplemente no pueden replicar.

Esta guía está escrita para equipos técnicos que crean integraciones personalizadas con GoHighLevel. Cubre la arquitectura API, la autenticación, los puntos finales clave, la configuración y la seguridad del webhook y patrones de integración prácticos para casos de uso comunes.

Conclusiones clave

• La API REST de GHL (v2) utiliza OAuth 2.0 para la autenticación y admite todos los objetos principales de CRM.
• Los webhooks entrantes en los flujos de trabajo de GHL permiten que los sistemas externos activen automatizaciones de GHL en tiempo real
• Los webhooks salientes de GHL notifican a los sistemas externos cuando ocurren eventos de GHL (contacto creado, canalización actualizada, etc.)
• Los límites de velocidad son 100 solicitudes/10 segundos por ubicación; las operaciones por lotes y el almacenamiento en caché son importantes a escala
• GHL Marketplace le permite publicar integraciones como aplicaciones nativas de GHL para la instalación del cliente
• Los valores personalizados y los campos personalizados son los principales puntos de extensión de datos para almacenar el estado de la integración.
• La verificación de la carga útil del webhook mediante el encabezado de firma GHL evita solicitudes falsificadas
• La mayoría de las integraciones de GHL siguen cuatro patrones: sincronización de contactos, automatización activada por eventos, puenteo de canales o agregación de informes.

---

Descripción general de la arquitectura API de GHL

La API de GoHighLevel (versión 2 a partir de 2026) es una API REST estándar con cuerpos de solicitud y respuesta JSON. La URL base es:

https://services.leadconnectorhq.com

La API organiza los recursos en estos espacios de nombres principales:

La documentación API completa está disponible en https://highlevel.stoplight.io/docs/integrations/.

---

Autenticación: configuración de OAuth 2.0

La API de GHL utiliza OAuth 2.0 para toda la autenticación. Hay dos contextos de autenticación:

1. Clave API a nivel de agencia (para administración de subcuentas)

Para integraciones de servidor a servidor que administran múltiples subcuentas, use la clave API de agencia:

• Generado en Configuración de la agencia > Claves API
• Alcance de operaciones a nivel de agencia (creación/administración de subcuentas)

2. Subcuenta OAuth (para integraciones por ubicación)

Para integraciones que operan dentro de una única subcuenta (el caso más común):

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

Alcances requeridos para operaciones comunes:

Solicite solo los alcances que necesita: un alcance mínimo es una práctica recomendada de seguridad.

---

Operaciones principales de API: contactos

La API de contactos es el punto final más utilizado en las integraciones de GHL.

Crear o actualizar un contacto:

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

Respuesta (201 creada):

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

Buscar un contacto por correo electrónico (para deduplicación):

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

Busque siempre antes de crear para evitar registros de contactos duplicados.

Agregar una etiqueta a un contacto:

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

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

Operaciones Masivas:

GHL admite la creación masiva de contactos a través del punto final POST /contacts/bulk (verifique en los documentos API actuales su versión de GHL). Para importaciones de más de 500 contactos, utilice el punto final masivo con lotes de 100 contactos por solicitud para mantenerse dentro de los límites de velocidad.

---

API de oportunidades y canalizaciones

Crear una oportunidad:

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

Mover la oportunidad a una nueva etapa:

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

{
  "pipelineStageId": "NEW_STAGE_ID"
}

Patrón de integración común: CRM externo → GHL Pipeline Sync

Cuando se crea una oferta en un sistema externo (por ejemplo, Salesforce), su código de integración:

1. Busca en GHL el contacto por correo electrónico
2. Crea el contacto si no lo encuentra.
3. Crea una oportunidad GHL vinculada al contacto.
4. Almacena el ID de oportunidad de GHL como un campo personalizado en Salesforce para sincronización bidireccional.

---

Webhooks entrantes: activación de GHL desde sistemas externos

Los webhooks entrantes permiten que los sistemas externos activen flujos de trabajo de GHL. Este es el mecanismo principal para la integración basada en eventos.

Creación de un activador de webhook entrante en GHL:

1. Vaya a Automatización > Flujos de trabajo > Nuevo flujo de trabajo
2. Seleccione "Webhook entrante" como tipo de activador.
3. GHL genera una URL única: CÓDIGO0
4. Configure qué datos utiliza el flujo de trabajo de la carga útil del webhook.

Envío de datos al webhook entrante:

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 crea o actualiza un contacto a partir de los campos de carga útil que reconoce (nombre, apellido, correo electrónico, teléfono) y hace que los campos customData estén disponibles como variables en el flujo de trabajo.

Casos de uso para webhooks entrantes:

• pedido de comercio electrónico realizado → desencadenar secuencia posterior a la compra
• Ticket de soporte creado → agregar etiqueta "soporte activo", pausar secuencias de marketing
• Pago recibido → mover el proceso a "Ganado", activar el flujo de trabajo de incorporación
• Registro de prueba → iniciar la secuencia de incorporación de SaaS
• Formulario enviado en un sitio de terceros → capturar clientes potenciales en GHL CRM

---

Webhooks salientes: GHL notifica a sistemas externos

Los webhooks salientes envían datos desde GHL a sistemas externos cuando ocurren eventos de GHL.

Configuración de Webhooks salientes en GHL:

Navegue a Configuración > Integraciones > Webhooks (nivel de subcuenta) o agregue una acción de webhook dentro de un flujo de trabajo.

Eventos salientes nativos de GHL (disponibles en Configuración > Webhooks):

• Contacto creado
• Contacto actualizado
• Contacto eliminado
• Oportunidad creada/actualizada/eliminada
• Formulario enviado
• Cita reservada/cancelada/no presentada
• Mensaje de conversación (entrante)
• Llamada iniciada/finalizada

Acción del webhook del flujo de trabajo de GHL:

Para un control más granular, agregue una acción "Enviar webhook" dentro de un flujo de trabajo. Esto se activa solo cuando el flujo de trabajo llega a ese paso, lo que le permite controlar exactamente qué eventos notifican a los sistemas externos y qué carga útil reciben.

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

Utilice la sintaxis de valores personalizados de GHL ({{variable.path}}) para incluir datos dinámicos de eventos y contactos en la carga útil.

---

Seguridad del webhook: verificación de firma

GHL firma webhooks salientes con una firma HMAC-SHA256. Su punto final receptor debe verificar esta firma para evitar solicitudes falsificadas.

Proceso de verificación:

GHL incluye un encabezado de firma con cada solicitud de webhook:

X-GHL-Signature: sha256=COMPUTED_HMAC

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

Utilice siempre crypto.timingSafeEqual para comparar: la igualdad de cadenas es vulnerable a ataques de sincronización.

El secreto de su webhook se establece cuando crea el webhook en la configuración de GHL.

---

Limitación de tasas y mejores prácticas

GHL impone límites de tarifas en el acceso a la API. A partir de 2026, el límite estándar es de aproximadamente 100 solicitudes cada 10 segundos por ubicación. Superar esto devuelve una respuesta 429 Too Many Requests.

Estrategias para mantenerse dentro de los límites de tarifas:

1. Implementar retroceso 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. Búsquedas de contactos en caché: No busque en GHL por correo electrónico cada evento entrante. Almacene en caché las búsquedas de ID de contacto en Redis o su base de datos con un TTL de 15 minutos. La mayoría de los flujos de integración involucran los mismos contactos repetidamente.

3. Actualizaciones de contactos por lotes: Si está actualizando campos personalizados para 500 contactos después de un proceso de datos masivo, realice las actualizaciones en grupos de 10 con un retraso de 100 ms entre lotes en lugar de activar los 500 simultáneamente.

4. Utilice webhooks en lugar de encuestas: Nunca sondee la API de GHL para detectar cambios (por ejemplo, verificar cada minuto si se crearon nuevos contactos). Utilice los webhooks salientes de GHL para recibir notificaciones cuando ocurran eventos. Esto elimina el consumo de límite de tasa relacionado con el sondeo.

---

Creación de una aplicación de mercado GHL

Si está creando una integración para varios clientes de GHL, considere publicarla como una aplicación de GHL Marketplace. Esto permite a los usuarios de GHL instalar su integración con un solo clic, utilizando OAuth para la autenticación, sin necesidad de compartir claves API manualmente.

Requisitos para cotizar en el mercado:

• Implementación de OAuth 2.0
• Política de privacidad y condiciones de servicio URL
• Icono y descripción de la aplicación.
• Manejo de webhooks para los eventos a los que se suscribe su aplicación
• Proceso de revisión y aprobación de GHL (normalmente de 1 a 2 semanas)

Beneficios de la distribución en Marketplace:

• Instalación con un clic para usuarios de GHL
• OAuth maneja la autenticación (sin administración de claves API)
• Mayor capacidad de descubrimiento a través del mercado de GHL
• Posibilidad de cobrar por la integración a través de la infraestructura de facturación de GHL

Vale la pena seguir este camino si está creando una integración que utilizarían varias agencias o empresas de GHL: el apalancamiento de la distribución es significativo.

---

Patrones de integración comunes

Patrón 1: Sincronización de pedidos de comercio electrónico

• Webhook de pedidos de Shopify → su middleware → actualización de contacto de GHL + etiqueta + inscripción en el flujo de trabajo
• El middleware valida la carga útil, deduplica contactos y asigna datos de pedidos a campos personalizados de GHL

Patrón 2: Puente de ERP a CRM

• Factura de ERP (Odoo, QuickBooks) creada → webhook al middleware → oportunidad de GHL marcada como ganada + canalización movida
• Sincronización bidireccional: cambio de canalización de GHL → actualización del estado del pedido de ERP

Patrón 3: Cita + Sincronización de servicio de campo

• Cita GHL reservada → webhook saliente → La herramienta FSM crea trabajo
• Trabajo de FSM completado → webhook a GHL → mover canalización a Completado + activar secuencia de revisión

Patrón 4: Informes del almacén de datos

• Diariamente: la API de GHL extrae los contactos, oportunidades y eventos de comunicación del día anterior.
• Datos almacenados en su almacén de datos (BigQuery, Snowflake)
• Power BI o Looker se conecta al almacén de datos para realizar análisis avanzados multiplataforma

---

Preguntas frecuentes

¿Cuál es la diferencia entre la API v1 y v2 de GHL?

La API v2 de GHL (introducida alrededor de 2022-2023) utiliza OAuth 2.0 y un diseño REST más limpio en comparación con la autenticación de clave API de la v1. La API v2 tiene una cobertura de puntos finales más completa y mejor documentación. Se deben crear nuevas integraciones en la versión 2. GHL ha declarado su intención de dejar de usar la versión 1, pero aún no ha establecido un cronograma firme; consulte los anuncios de desarrolladores de GHL para conocer el estado actual.

¿Puedo utilizar la API de GHL para enviar mensajes SMS mediante programación?

Sí. Utilice el punto final POST /conversations/messages para enviar mensajes SMS a un contacto. Necesita el ID de la conversación (creado por POST /conversations/) y el número de teléfono del contacto. Asegúrese de que el contacto tenga el estado de aceptación de SMS antes de enviarlo; GHL aplica esto y el envío a contactos excluidos fallará. Incluya el parámetro type: "SMS" requerido y el número Twilio de su ubicación GHL como remitente.

¿Cómo manejo la paginación de la API GHL para conjuntos de datos grandes?

Los puntos finales de la lista de GHL devuelven resultados paginados. La respuesta incluye un objeto meta con total, currentPage y nextPage (o startAfterId basado en cursor). Implemente la paginación iterando a través de las páginas hasta que nextPage sea nulo o haya recopilado todos los registros. Para exportaciones de contactos grandes (más de 100 000 contactos), utilice la función de exportación masiva de GHL o comuníquese con el soporte de GHL para solicitar una exportación de datos; la paginación a través de la API para conjuntos de datos muy grandes es lenta y requiere muchos límites de velocidad.

¿Existe un entorno de pruebas para probar las integraciones de API de GHL?

GHL no tiene un entorno sandbox dedicado. Utilice una cuenta de prueba de GHL separada o una subcuenta de desarrollo para realizar pruebas. Cree contactos de prueba con correos electrónicos claramente etiquetados (por ejemplo, prueba+integració[email protected]) para distinguir los datos de prueba de los contactos reales. Limpie los datos de prueba con regularidad para mantener organizada su cuenta de desarrollo.

¿Cuál es la mejor manera de almacenar los ID de contacto de GHL en mi sistema externo?

Almacene el GHL contact.id (una cadena única) como un campo personalizado en su sistema externo (por ejemplo, una columna ghl_contact_id en su base de datos). Esto permite llamadas API directas al contacto correcto sin un paso de búsqueda. Al crear contactos en GHL, almacene la identificación devuelta inmediatamente. Para la sincronización bidireccional, almacene también la identificación única de su sistema como un campo personalizado de GHL (por ejemplo, external_user_id) para la búsqueda inversa.

---

Próximos pasos

La API y el sistema de webhook de GoHighLevel la convierten en una plataforma genuinamente extensible: no solo una herramienta de marketing sin código, sino un motor de comunicación con el cliente programable que puede integrarse con prácticamente cualquier sistema empresarial. La clave es crear integraciones limpias y bien probadas con un manejo adecuado de errores y verificación de firmas desde el principio.

Los servicios GoHighLevel de ECOSIRE incluyen desarrollo de integración de API personalizado. Nuestro equipo técnico crea integraciones GHL para plataformas de comercio electrónico, sistemas ERP, herramientas de gestión de servicios de campo y aplicaciones comerciales patentadas. Diseñamos integraciones con manejo adecuado de errores, gestión de límites de velocidad y monitoreo.

Comuníquese con nuestro equipo para analizar sus requisitos de integración personalizados y obtener un alcance técnico para su proyecto de integración GHL específico.