API GoHighLevel et Webhooks : intégrations personnalisées

Les intégrations natives de GoHighLevel et les connecteurs Zapier couvrent la plupart des cas d'utilisation standard, mais les entreprises disposant de flux de travail spécifiques, de systèmes propriétaires ou de volumes de données élevés doivent éventuellement travailler directement avec l'API de GHL. L'API REST GHL et le système de webhook offrent aux développeurs un accès programmatique complet aux contacts, pipelines, campagnes, rendez-vous, etc., permettant des intégrations que les outils sans code ne peuvent tout simplement pas reproduire.

Ce guide est rédigé pour les équipes techniques qui créent des intégrations personnalisées avec GoHighLevel. Il couvre l'architecture de l'API, l'authentification, les points de terminaison clés, la configuration et la sécurité des webhooks, ainsi que les modèles d'intégration pratiques pour les cas d'utilisation courants.

Points clés à retenir

• L'API REST (v2) de GHL utilise OAuth 2.0 pour l'authentification et prend en charge tous les principaux objets CRM
• Les webhooks entrants dans les workflows GHL permettent aux systèmes externes de déclencher les automatisations GHL en temps réel
• Les webhooks sortants de GHL avertissent les systèmes externes lorsque des événements GHL se produisent (contact créé, pipeline mis à jour, etc.)
• Les limites de débit sont de 100 requêtes/10 secondes par emplacement — les opérations par lots et la mise en cache sont importantes à grande échelle
• Le GHL Marketplace vous permet de publier des intégrations sous forme d'applications natives GHL pour l'installation du client.
• Les valeurs personnalisées et les champs personnalisés sont les principaux points d'extension des données pour stocker l'état d'intégration
• La vérification de la charge utile du Webhook à l'aide de l'en-tête de signature GHL empêche les requêtes usurpées
• La plupart des intégrations GHL suivent quatre modèles : synchronisation des contacts, automatisation déclenchée par un événement, pontage du pipeline ou agrégation de rapports

---

Présentation de l'architecture de l'API GHL

L'API de GoHighLevel (version 2 à partir de 2026) est une API REST standard avec des corps de requête et de réponse JSON. L'URL de base est :

https://services.leadconnectorhq.com

L'API organise les ressources dans ces espaces de noms principaux :

La documentation complète de l'API est disponible sur https://highlevel.stoplight.io/docs/integrations/.

---

Authentification : configuration OAuth 2.0

L'API de GHL utilise OAuth 2.0 pour toutes les authentifications. Il existe deux contextes d'authentification :

1. Clé API au niveau de l'agence (pour la gestion des sous-comptes)

Pour les intégrations de serveur à serveur qui gèrent plusieurs sous-comptes, utilisez la clé API de l'agence :

• Généré dans Paramètres de l'agence > Clés API
• Adapté aux opérations au niveau de l'agence (création/gestion de sous-comptes)

2. Sous-compte OAuth (pour les intégrations par emplacement)

Pour les intégrations opérant au sein d’un seul sous-compte (cas le plus courant) :

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

Étendues requises pour les opérations courantes :

Demandez uniquement les étendues dont vous avez besoin : une portée minimale est une bonne pratique en matière de sécurité.

---

Opérations principales de l'API : contacts

L'API de contacts est le point de terminaison le plus fréquemment utilisé dans les intégrations GHL.

Créer ou mettre à jour un contact :

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

Réponse (201 créées) :

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

Rechercher un contact par email (pour la déduplication) :

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

Recherchez toujours avant de créer pour éviter les enregistrements de contact en double.

Ajouter une balise à un contact :

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

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

Opérations groupées :

GHL prend en charge la création groupée de contacts via le point de terminaison POST /contacts/bulk (vérifiez dans la documentation API actuelle pour votre version GHL). Pour les importations de plus de 500 contacts, utilisez le point de terminaison en masse avec des lots de 100 contacts par demande pour respecter les limites de débit.

---

API de pipeline et d'opportunité

Créer une opportunité :

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

Déplacer l'opportunité vers une nouvelle étape :

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

{
  "pipelineStageId": "NEW_STAGE_ID"
}

Modèle d'intégration courant : CRM externe → GHL Pipeline Sync

Lorsqu'une transaction est créée dans un système externe (par exemple, Salesforce), votre code d'intégration :

1. Recherche GHL pour le contact par email
2. Crée le contact s'il n'est pas trouvé
3. Crée une opportunité GHL liée au contact
4. Stocke l'ID d'opportunité GHL en tant que champ personnalisé dans Salesforce pour la synchronisation bidirectionnelle

---

Webhooks entrants : déclenchement de GHL à partir de systèmes externes

Les webhooks entrants permettent aux systèmes externes de déclencher des flux de travail GHL. Il s’agit du principal mécanisme d’intégration événementielle.

Création d'un déclencheur Webhook entrant dans GHL :

1. Accédez à Automation > Workflows > Nouveau workflow.
2. Sélectionnez « Webhook entrant » comme type de déclencheur
3. GHL génère une URL unique : https://services.leadconnectorhq.com/hooks/YOUR_UNIQUE_HOOK_ID/webhook-trigger
4. Configurez les données que le workflow utilise à partir de la charge utile du webhook

Envoi de données au webhook entrant :

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 crée ou met à jour un contact à partir des champs de charge utile qu'il reconnaît (prénom, nom, e-mail, téléphone) et rend les champs customData disponibles en tant que variables dans le workflow.

Cas d'utilisation des webhooks entrants :

• commande de commerce électronique passée → déclencher la séquence post-achat
• Ticket de support créé → ajouter la balise "active-support", suspendre les séquences marketing
• Paiement reçu → déplacer le pipeline vers « Gagné », déclencher le workflow d'intégration
• Inscription à l'essai → démarrer la séquence d'intégration SaaS
• Formulaire soumis sur un site tiers → capturer le prospect dans GHL CRM

---

Webhooks sortants : GHL notifiant les systèmes externes

Les webhooks sortants envoient des données de GHL vers des systèmes externes lorsque des événements GHL se produisent.

Configuration des webhooks sortants dans GHL :

Accédez à Paramètres > Intégrations > Webhooks (niveau du sous-compte) ou ajoutez une action webhook dans un workflow.

Événements sortants natifs GHL (disponibles dans Paramètres > Webhooks) :

• Contact créé
• Contact mis à jour
• Contact supprimé
• Opportunité créée/mise à jour/supprimée
• Formulaire soumis
• Rendez-vous pris/annulé/non présenté
• Message de conversation (entrant)
• Appel démarré/terminé

Action du webhook de flux de travail GHL :

Pour un contrôle plus granulaire, ajoutez une action « Envoyer un Webhook » dans un flux de travail. Cela se déclenche uniquement lorsque le flux de travail atteint cette étape, vous permettant de contrôler exactement quels événements notifient les systèmes externes et quelle charge utile ils reçoivent.

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

Utilisez la syntaxe de valeur personnalisée de GHL ({{variable.path}}) pour inclure des données dynamiques de contact et d'événement dans la charge utile.

---

Sécurité des webhooks : vérification de la signature

GHL signe les webhooks sortants avec une signature HMAC-SHA256. Votre point de terminaison de réception doit vérifier cette signature pour éviter les demandes usurpées.

Processus de vérification :

GHL inclut un en-tête de signature avec chaque demande de webhook :

X-GHL-Signature: sha256=COMPUTED_HMAC

Votre serveur vérifie :

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

Utilisez toujours crypto.timingSafeEqual à des fins de comparaison : l'égalité des chaînes est vulnérable aux attaques de synchronisation.

Le secret de votre webhook est défini lorsque vous créez le webhook dans les paramètres de GHL.

---

Limitation du débit et bonnes pratiques

GHL applique des limites de débit sur l'accès à l'API. À partir de 2026, la limite standard est d’environ 100 requêtes toutes les 10 secondes et par emplacement. Le dépassement renvoie une réponse 429 Too Many Requests.

Stratégies pour rester dans les limites de taux :

1. Implémenter un recul exponentiel :

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. Recherches de contacts en cache : Ne recherchez pas GHL par e-mail pour chaque événement entrant. Mettez en cache les recherches d’ID de contact dans Redis ou votre base de données avec une durée de vie de 15 minutes. La plupart des flux d’intégration impliquent les mêmes contacts de manière répétée.

3. Mises à jour des contacts par lots : Si vous mettez à jour des champs personnalisés pour 500 contacts après un traitement de données groupées, regroupez les mises à jour par groupes de 10 avec un délai de 100 ms entre les lots plutôt que de lancer les 500 simultanément.

4. Utilisez des webhooks au lieu d'interroger : N'interrogez jamais l'API de GHL pour connaître les modifications (par exemple, en vérifiant toutes les minutes si de nouveaux contacts ont été créés). Utilisez les webhooks sortants de GHL pour recevoir des notifications lorsque des événements se produisent. Cela élimine la consommation de limite de débit liée aux interrogations.

---

Créer une application GHL Marketplace

Si vous créez une intégration pour plusieurs clients GHL, envisagez de la publier en tant qu'application GHL Marketplace. Cela permet aux utilisateurs de GHL d'installer votre intégration en un seul clic, en utilisant OAuth pour l'authentification — aucun partage manuel de clé API n'est requis.

Exigences pour l'inscription sur le marché :

• Implémentation OAuth 2.0
• Politique de confidentialité et conditions d'utilisation URL
• Icône et description de l'application
• Gestion des webhooks pour les événements auxquels votre application est abonnée
• Processus d'examen et d'approbation du GHL (généralement 1 à 2 semaines)

Avantages de la distribution sur le marché :

• Installation en un clic pour les utilisateurs de GHL
• OAuth gère l'authentification (pas de gestion des clés API)
• Découverte accrue via le marché de GHL
• Possibilité de facturer l'intégration via l'infrastructure de facturation de GHL

Cette voie vaut la peine d'être suivie si vous construisez une intégration que plusieurs agences ou entreprises GHL utiliseraient : l'effet de levier de distribution est important.

---

Modèles d'intégration courants

Modèle 1 : synchronisation des commandes de commerce électronique

• Webhook de commande Shopify → votre middleware → mise à jour des contacts GHL + tag + inscription au workflow
• Le middleware valide la charge utile, déduplique les contacts, mappe les données de commande aux champs personnalisés GHL

Modèle 2 : Pont ERP vers CRM

• Facture ERP (Odoo, QuickBooks) créée → webhook vers middleware → opportunité GHL marquée Gagnée + pipeline déplacé
• Synchronisation bidirectionnelle : changement de pipeline GHL → mise à jour de l'état des commandes ERP

Modèle 3 : rendez-vous + synchronisation du service sur le terrain

• Rendez-vous GHL pris → webhook sortant → L'outil FSM crée un emploi
• Travail FSM terminé → webhook vers GHL → déplacer le pipeline vers Terminé + déclencher la séquence de révision

Modèle 4 : Rapports sur l'entrepôt de données

• Quotidiennement : l'API GHL extrait les contacts, les opportunités et les événements de communication de la veille.
• Données stockées dans votre entrepôt de données (BigQuery, Snowflake)
• Power BI ou Looker se connecte à l'entrepôt de données pour des analyses multiplateformes avancées

---

Questions fréquemment posées

Quelle est la différence entre les API v1 et v2 de GHL ?

L'API v2 de GHL (introduite vers 2022-2023) utilise OAuth 2.0 et une conception REST plus propre par rapport à l'authentification par clé API de la v1. L'API v2 offre une couverture plus complète des points de terminaison et une meilleure documentation. Les nouvelles intégrations devraient être construites sur la v2. GHL a déclaré son intention de déprécier la v1 mais n'a pas encore fixé de calendrier ferme – consultez les annonces des développeurs de GHL pour connaître l'état actuel.

Puis-je utiliser l'API de GHL pour envoyer des messages SMS par programmation ?

Oui. Utilisez le point de terminaison POST /conversations/messages pour envoyer des messages SMS à un contact. Vous avez besoin de l'ID de conversation (créé par POST /conversations/) et du numéro de téléphone du contact. Assurez-vous que le contact a le statut d’inscription aux SMS avant de l’envoyer – GHL l’applique et l’envoi aux contacts désinscrits échouera. Incluez le paramètre type: "SMS" requis et le numéro Twilio de votre emplacement GHL en tant qu'expéditeur.

Comment gérer la pagination de l'API GHL pour les grands ensembles de données ?

Les points de terminaison de la liste GHL renvoient des résultats paginés. La réponse inclut un objet meta avec total, currentPage et nextPage (ou startAfterId basé sur un curseur). Implémentez la pagination en parcourant les pages jusqu'à ce que nextPage soit nul ou que vous ayez collecté tous les enregistrements. Pour les exportations de contacts volumineuses (plus de 100 000 contacts), utilisez la fonction d'exportation groupée de GHL ou contactez l'assistance GHL pour demander une exportation de données : la pagination via l'API pour de très grands ensembles de données est lente et gourmande en limites de débit.

Existe-t-il un environnement sandbox pour tester les intégrations de l'API GHL ?

GHL ne dispose pas d'un environnement sandbox dédié. Utilisez un compte d'essai GHL distinct ou un sous-compte de développement pour les tests. Créez des contacts de test avec des e-mails clairement étiquetés (par exemple, [email protected]) pour distinguer les données de test des contacts réels. Nettoyez régulièrement les données de test pour garder votre compte de développement organisé.

Quelle est la meilleure façon de stocker les ID de contact GHL dans mon système externe ?

Stockez le GHL contact.id (une chaîne unique) en tant que champ personnalisé dans votre système externe (par exemple, une colonne ghl_contact_id dans votre base de données). Cela permet d’appeler directement l’API au bon contact sans étape de recherche. Lors de la création de contacts dans GHL, stockez immédiatement l’identifiant renvoyé. Pour la synchronisation bidirectionnelle, stockez également l'ID unique de votre système en tant que champ personnalisé GHL (par exemple, external_user_id) pour la recherche inversée.

---

Prochaines étapes

L'API et le système de webhook de GoHighLevel en font une plate-forme véritablement extensible : il ne s'agit pas seulement d'un outil de marketing sans code, mais d'un moteur de communication client programmable qui peut s'intégrer à pratiquement n'importe quel système d'entreprise. La clé est de créer des intégrations propres et bien testées avec une gestion appropriée des erreurs et une vérification des signatures dès le départ.

Les services GoHighLevel d'ECOSIRE incluent le développement d'intégrations d'API personnalisées. Notre équipe technique crée des intégrations GHL pour les plateformes de commerce électronique, les systèmes ERP, les outils de gestion des services sur le terrain et les applications commerciales propriétaires. Nous concevons des intégrations avec une gestion appropriée des erreurs, une gestion des limites de débit et une surveillance.

Contactez notre équipe pour discuter de vos exigences d'intégration personnalisées et obtenir une portée technique pour votre projet d'intégration GHL spécifique.