GoHighLevel API und Webhooks: Benutzerdefinierte Integrationen

Die nativen Integrationen und Zapier-Konnektoren von GoHighLevel decken die meisten Standardanwendungsfälle ab, aber Unternehmen mit spezifischen Arbeitsabläufen, proprietären Systemen oder hohen Datenmengen müssen letztendlich direkt mit der API von GHL arbeiten. Die GHL REST API und das Webhook-System ermöglichen Entwicklern vollständigen programmatischen Zugriff auf Kontakte, Pipelines, Kampagnen, Termine und mehr – und ermöglichen so Integrationen, die No-Code-Tools einfach nicht reproduzieren können.

Dieser Leitfaden richtet sich an technische Teams, die benutzerdefinierte Integrationen mit GoHighLevel erstellen. Es behandelt die API-Architektur, Authentifizierung, wichtige Endpunkte, Webhook-Einrichtung und -Sicherheit sowie praktische Integrationsmuster für häufige Anwendungsfälle.

Wichtige Erkenntnisse

• Die REST-API (v2) von GHL verwendet OAuth 2.0 zur Authentifizierung und unterstützt alle wichtigen CRM-Objekte – Eingehende Webhooks in GHL-Workflows ermöglichen es externen Systemen, GHL-Automatisierungen in Echtzeit auszulösen – Ausgehende Webhooks von GHL benachrichtigen externe Systeme, wenn GHL-Ereignisse auftreten (Kontakt erstellt, Pipeline aktualisiert usw.) – Die Ratenbegrenzung liegt bei 100 Anfragen/10 Sekunden pro Standort – Batch-Vorgänge und Caching sind im großen Maßstab wichtig – Der GHL Marketplace ermöglicht Ihnen die Veröffentlichung von Integrationen als GHL-native Apps zur Kundeninstallation – Benutzerdefinierte Werte und benutzerdefinierte Felder sind die primären Datenerweiterungspunkte zum Speichern des Integrationsstatus – Die Überprüfung der Webhook-Nutzlast mithilfe des GHL-Signatur-Headers verhindert gefälschte Anfragen – Die meisten GHL-Integrationen folgen vier Mustern: Kontaktsynchronisierung, ereignisgesteuerte Automatisierung, Pipeline-Bridging oder Berichtsaggregation

---

Übersicht über die GHL-API-Architektur

Die API von GoHighLevel (Version 2 ab 2026) ist eine Standard-REST-API mit JSON-Anfrage- und Antworttexten. Die Basis-URL lautet:

https://services.leadconnectorhq.com

Die API organisiert Ressourcen in diesen primären Namespaces:

Die vollständige API-Dokumentation ist unter https://highlevel.stoplight.io/docs/integrations/ verfügbar.

---

Authentifizierung: OAuth 2.0-Setup

Die API von GHL verwendet OAuth 2.0 für die gesamte Authentifizierung. Es gibt zwei Authentifizierungskontexte:

1. API-Schlüssel auf Agenturebene (für die Unterkontoverwaltung)

Für Server-zu-Server-Integrationen, die mehrere Unterkonten verwalten, verwenden Sie den Agentur-API-Schlüssel: – Wird in Agentureinstellungen > API-Schlüssel generiert

• Auf Operationen auf Agenturebene beschränkt (Erstellen/Verwalten von Unterkonten)

2. Unterkonto-OAuth (für Integrationen pro Standort)

Für Integrationen, die innerhalb eines einzelnen Unterkontos ausgeführt werden (der häufigste Fall):

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

Für allgemeine Vorgänge erforderliche Bereiche:

Fordern Sie nur die Bereiche an, die Sie benötigen – ein minimaler Umfang ist eine bewährte Sicherheitsmethode.

---

Kern-API-Operationen: Kontakte

Die Kontakt-API ist der am häufigsten verwendete Endpunkt in GHL-Integrationen.

Kontakt erstellen oder aktualisieren:

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

Antwort (201 erstellt):

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

Nach einem Kontakt per E-Mail suchen (zur Deduplizierung):

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

Suchen Sie immer vor dem Erstellen, um doppelte Kontaktdatensätze zu vermeiden.

Tag zu einem Kontakt hinzufügen:

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

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

Massenoperationen:

GHL unterstützt die Massenkontakterstellung über den Endpunkt POST /contacts/bulk (überprüfen Sie dies in den aktuellen API-Dokumenten für Ihre GHL-Version). Für den Import von mehr als 500 Kontakten verwenden Sie den Massenendpunkt mit Stapeln von 100 Kontakten pro Anfrage, um innerhalb der Ratengrenzen zu bleiben.

---

Pipeline- und Opportunity-API

Eine Gelegenheit erstellen:

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

Chance in eine neue Phase bringen:

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

{
  "pipelineStageId": "NEW_STAGE_ID"
}

Gemeinsames Integrationsmuster: Externes CRM → GHL-Pipeline-Synchronisierung

Wenn ein Deal in einem externen System (z. B. Salesforce) erstellt wird, lautet Ihr Integrationscode:

1. Durchsucht GHL nach dem Kontakt per E-Mail
2. Erstellt den Kontakt, wenn er nicht gefunden wird
3. Erstellt eine mit dem Kontakt verknüpfte GHL-Opportunity
4. Speichert die GHL-Opportunity-ID als benutzerdefiniertes Feld in Salesforce für die bidirektionale Synchronisierung

---

Eingehende Webhooks: GHL von externen Systemen auslösen

Durch eingehende Webhooks können externe Systeme GHL-Workflows auslösen. Dies ist der primäre Mechanismus für die ereignisgesteuerte Integration.

Erstellen eines eingehenden Webhook-Triggers in GHL:

1. Navigieren Sie zu Automatisierung > Workflows > Neuer Workflow
2. Wählen Sie als Triggertyp „Inbound Webhook“.
3. GHL generiert eine eindeutige URL: https://services.leadconnectorhq.com/hooks/YOUR_UNIQUE_HOOK_ID/webhook-trigger
4. Konfigurieren Sie, welche Daten der Workflow aus der Webhook-Nutzlast verwendet

Senden von Daten an den eingehenden 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 erstellt oder aktualisiert einen Kontakt aus den von ihm erkannten Payload-Feldern (Vorname, Nachname, E-Mail, Telefon) und stellt die customData-Felder als Variablen im Workflow zur Verfügung.

Anwendungsfälle für eingehende Webhooks:

• E-Commerce-Bestellung aufgegeben → Nachkaufsequenz auslösen
• Support-Ticket erstellt → „Active-Support“-Tag hinzufügen, Marketingsequenzen pausieren
• Zahlung erhalten → Pipeline auf „Gewonnen“ verschieben, Onboarding-Workflow auslösen
• Probeanmeldung → SaaS-Onboarding-Sequenz starten
• Formular auf der Website eines Drittanbieters eingereicht → Lead in GHL CRM erfassen

---

Ausgehende Webhooks: GHL benachrichtigt externe Systeme

Ausgehende Webhooks senden Daten von GHL an externe Systeme, wenn GHL-Ereignisse auftreten.

Konfigurieren ausgehender Webhooks in GHL:

Navigieren Sie zu Einstellungen > Integrationen > Webhooks (Unterkontoebene) oder fügen Sie eine Webhook-Aktion innerhalb eines Workflows hinzu.

GHL Native Outbound Events (verfügbar unter Einstellungen > Webhooks):

• Kontakt erstellt
• Kontakt aktualisiert
• Kontakt gelöscht
• Gelegenheit erstellt/aktualisiert/gelöscht
• Formular eingereicht
• Termin gebucht/abgesagt/nicht erschienen
• Konversationsnachricht (eingehend)
• Anruf gestartet/beendet

GHL-Workflow-Webhook-Aktion:

Für eine detailliertere Kontrolle fügen Sie die Aktion „Webhook senden“ in einen Workflow ein. Dies wird nur ausgelöst, wenn der Workflow diesen Schritt erreicht, sodass Sie genau steuern können, welche Ereignisse externe Systeme benachrichtigen und welche Nutzlast sie erhalten.

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

Verwenden Sie die benutzerdefinierte Wertesyntax ({{variable.path}}) von GHL, um dynamische Kontakt- und Ereignisdaten in die Nutzlast einzuschließen.

---

Webhook-Sicherheit: Signaturüberprüfung

GHL signiert ausgehende Webhooks mit einer HMAC-SHA256-Signatur. Ihr empfangender Endpunkt sollte diese Signatur überprüfen, um gefälschte Anfragen zu verhindern.

Verifizierungsprozess:

GHL fügt jeder Webhook-Anfrage einen Signatur-Header hinzu:

X-GHL-Signature: sha256=COMPUTED_HMAC

Ihr Server überprüft:

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

Verwenden Sie zum Vergleich immer crypto.timingSafeEqual – String-Gleichheit ist anfällig für Timing-Angriffe.

Ihr Webhook-Geheimnis wird festgelegt, wenn Sie den Webhook in den GHL-Einstellungen erstellen.

---

Ratenbegrenzung und Best Practices

GHL erzwingt Ratenbeschränkungen für den API-Zugriff. Ab 2026 beträgt das Standardlimit etwa 100 Anfragen pro 10 Sekunden pro Standort. Bei Überschreitung wird eine 429 Too Many Requests-Antwort zurückgegeben.

Strategien zur Einhaltung der Tarifgrenzen:

1. Exponentiellen Backoff implementieren:

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. Cache-Kontaktsuchen: Durchsuchen Sie GHL nicht per E-Mail nach jedem eingehenden Ereignis. Zwischenspeichern von Kontakt-ID-Suchen in Redis oder Ihrer Datenbank mit einer 15-minütigen TTL. Bei den meisten Integrationsabläufen sind dieselben Kontakte immer wieder involviert.

3. Batch-Kontaktaktualisierungen: Wenn Sie benutzerdefinierte Felder für 500 Kontakte nach einem Massendatenprozess aktualisieren, stapeln Sie die Aktualisierungen in Gruppen von 10 mit einer Verzögerung von 100 ms zwischen den Stapeln, anstatt alle 500 gleichzeitig auszulösen.

4. Verwenden Sie Webhooks statt Polling: Fragen Sie niemals die API von GHL nach Änderungen ab (z. B. jede Minute prüfen, ob neue Kontakte erstellt wurden). Verwenden Sie die ausgehenden Webhooks von GHL, um Benachrichtigungen zu erhalten, wenn Ereignisse auftreten. Dadurch entfällt der Verbrauch von Polling-bedingten Ratenbegrenzungen.

---

Erstellen einer GHL Marketplace-App

Wenn Sie eine Integration für mehrere GHL-Kunden erstellen, sollten Sie erwägen, sie als GHL Marketplace-App zu veröffentlichen. Dadurch können GHL-Benutzer Ihre Integration mit einem einzigen Klick installieren und OAuth zur Authentifizierung verwenden – eine manuelle API-Schlüsselfreigabe ist nicht erforderlich.

Anforderungen für den Marktplatzeintrag:

• OAuth 2.0-Implementierung
• URLs zu Datenschutzrichtlinien und Nutzungsbedingungen
• App-Symbol und Beschreibung
• Webhook-Verarbeitung für die Ereignisse, die Ihre App abonniert
• GHL-Überprüfungs- und Genehmigungsprozess (normalerweise 1–2 Wochen)

Vorteile des Marktplatzvertriebs:

• Ein-Klick-Installation für GHL-Benutzer
• OAuth übernimmt die Authentifizierung (keine API-Schlüsselverwaltung)
• Erhöhte Auffindbarkeit durch den Marktplatz von GHL
• Möglichkeit, die Integration über die Abrechnungsinfrastruktur von GHL abzurechnen

Dieser Weg lohnt sich, wenn Sie eine Integration aufbauen, die mehrere GHL-Agenturen oder -Unternehmen nutzen würden – der Vertriebsvorteil ist erheblich.

---

Gemeinsame Integrationsmuster

Muster 1: E-Commerce-Auftragssynchronisierung

• Shopify-Bestell-Webhook → Ihre Middleware → GHL-Kontaktaktualisierung + Tag + Workflow-Registrierung
• Middleware validiert Nutzdaten, dedupliziert Kontakte und ordnet Bestelldaten benutzerdefinierten GHL-Feldern zu

Muster 2: ERP-zu-CRM-Brücke

• ERP-Rechnung (Odoo, QuickBooks) erstellt → Webhook zur Middleware → GHL-Opportunity als „Gewonnen“ markiert + Pipeline verschoben
• Zwei-Wege-Synchronisierung: Änderung der GHL-Pipeline → Aktualisierung des ERP-Bestellstatus

Muster 3: Termin + Außendienst-Synchronisierung

• GHL-Termin gebucht → ausgehender Webhook → FSM-Tool erstellt Job – FSM-Auftrag abgeschlossen → Webhook zu GHL → Pipeline auf „Abgeschlossen“ verschieben + Überprüfungssequenz auslösen

Muster 4: Data Warehouse-Berichterstellung

• Täglich: Die GHL-API ruft die Kontakte, Chancen und Kommunikationsereignisse des Vortages ab
• In Ihrem Data Warehouse gespeicherte Daten (BigQuery, Snowflake)
• Power BI oder Looker stellen eine Verbindung zum Data Warehouse her, um erweiterte plattformübergreifende Analysen zu ermöglichen

---

Häufig gestellte Fragen

Was ist der Unterschied zwischen der v1- und der v2-API von GHL?

Die v2-API von GHL (eingeführt etwa 2022–2023) verwendet OAuth 2.0 und ein saubereres REST-Design im Vergleich zur API-Schlüsselauthentifizierung von v1. Die v2-API bietet eine umfassendere Endpunktabdeckung und eine bessere Dokumentation. Neue Integrationen sollten auf v2 aufbauen. GHL hat seine Absicht bekundet, v1 abzuschaffen, hat jedoch noch keinen festen Zeitplan festgelegt – den aktuellen Status finden Sie in den Entwicklerankündigungen von GHL.

Kann ich die API von GHL verwenden, um SMS-Nachrichten programmgesteuert zu senden?

Ja. Verwenden Sie den Endpunkt POST /conversations/messages, um SMS-Nachrichten an einen Kontakt zu senden. Sie benötigen die Konversations-ID (erstellt von POST /conversations/) und die Telefonnummer des Kontakts. Stellen Sie vor dem Senden sicher, dass der Kontakt den SMS-Opt-in-Status hat – GHL erzwingt dies und das Senden an deaktivierte Kontakte schlägt fehl. Geben Sie den erforderlichen Parameter type: "SMS" und die Twilio-Nummer Ihres GHL-Standorts als Absender an.

Wie gehe ich mit der GHL-API-Paginierung für große Datensätze um?

Die Listenendpunkte von GHL geben paginierte Ergebnisse zurück. Die Antwort enthält ein meta-Objekt mit total, currentPage und nextPage (oder den Cursor-basierten startAfterId). Implementieren Sie die Paginierung, indem Sie die Seiten durchlaufen, bis nextPage null ist oder Sie alle Datensätze gesammelt haben. Für große Kontaktexporte (über 100.000 Kontakte) nutzen Sie die Massenexportfunktion von GHL oder wenden Sie sich an den GHL-Support, um einen Datenexport anzufordern – das Paginieren über die API für sehr große Datensätze ist langsam und geschwindigkeitsbegrenzend.

Gibt es eine Sandbox-Umgebung zum Testen von GHL-API-Integrationen?

GHL verfügt nicht über eine dedizierte Sandbox-Umgebung. Verwenden Sie zum Testen ein separates GHL-Testkonto oder ein Entwicklungsunterkonto. Erstellen Sie Testkontakte mit klar gekennzeichneten E-Mails (z. B. [email protected]), um Testdaten von echten Kontakten zu unterscheiden. Bereinigen Sie die Testdaten regelmäßig, um Ihr Entwicklungskonto organisiert zu halten.

Wie speichere ich GHL-Kontakt-IDs am besten in meinem externen System?

Speichern Sie den GHL-contact.id (eine eindeutige Zeichenfolge) als benutzerdefiniertes Feld in Ihrem externen System (z. B. eine ghl_contact_id-Spalte in Ihrer Datenbank). Dies ermöglicht direkte API-Aufrufe an den richtigen Kontakt ohne Suchschritt. Speichern Sie beim Erstellen von Kontakten in GHL die zurückgegebene ID sofort. Speichern Sie für die bidirektionale Synchronisierung auch die eindeutige ID Ihres Systems als benutzerdefiniertes GHL-Feld (z. B. external_user_id) für die umgekehrte Suche.

---

Nächste Schritte

Die API und das Webhook-System von GoHighLevel machen es zu einer wirklich erweiterbaren Plattform – nicht nur zu einem No-Code-Marketingtool, sondern zu einer programmierbaren Kundenkommunikations-Engine, die in praktisch jedes Geschäftssystem integriert werden kann. Der Schlüssel liegt darin, saubere, gut getestete Integrationen mit ordnungsgemäßer Fehlerbehandlung und Signaturüberprüfung von Anfang an zu erstellen.

Die GoHighLevel-Dienste von ECOSIRE umfassen die Entwicklung einer benutzerdefinierten API-Integration. Unser technisches Team erstellt GHL-Integrationen für E-Commerce-Plattformen, ERP-Systeme, Tools für das Außendienstmanagement und proprietäre Geschäftsanwendungen. Wir entwerfen Integrationen mit ordnungsgemäßer Fehlerbehandlung, Ratenlimitverwaltung und Überwachung.

Kontaktieren Sie unser Team, um Ihre individuellen Integrationsanforderungen zu besprechen und einen technischen Rahmen für Ihr spezifisches GHL-Integrationsprojekt zu erhalten.