GoHighLevel API ve Web Kancaları: Özel Entegrasyonlar

GoHighLevel'in yerel entegrasyonları ve Zapier konnektörleri standart kullanım durumlarının çoğunu kapsar, ancak belirli iş akışlarına, özel sistemlere veya yüksek veri hacimlerine sahip işletmelerin sonuçta doğrudan GHL'nin API'si ile çalışması gerekir. GHL REST API ve webhook sistemi, geliştiricilere kişilere, işlem hatlarına, kampanyalara, randevulara ve daha fazlasına tam programlı erişim sağlar; kodsuz araçların kopyalayamayacağı entegrasyonlara olanak tanır.

Bu kılavuz, GoHighLevel ile özel entegrasyonlar oluşturan teknik ekipler için yazılmıştır. API mimarisini, kimlik doğrulamayı, önemli uç noktaları, webhook kurulumunu ve güvenliğini ve yaygın kullanım örneklerine yönelik pratik entegrasyon modellerini kapsar.

Önemli Çıkarımlar

• GHL'nin REST API'si (v2), kimlik doğrulama için OAuth 2.0'ı kullanır ve tüm önemli CRM nesnelerini destekler
• GHL iş akışlarındaki gelen web kancaları, harici sistemlerin GHL otomasyonlarını gerçek zamanlı olarak tetiklemesine olanak tanır
• GHL'den giden web kancaları, GHL olayları meydana geldiğinde (kişi oluşturulduğu, işlem hattı güncellendiği vb.) harici sistemleri bilgilendirir.
• Hız sınırları konum başına 100 istek/10 saniyedir — toplu işlemler ve önbelleğe alma geniş ölçekte önemlidir
• GHL Marketplace, entegrasyonları müşteri kurulumu için GHL'ye özgü uygulamalar olarak yayınlamanıza olanak tanır
• Özel değerler ve özel alanlar, entegrasyon durumunu depolamak için birincil veri uzantısı noktalarıdır
• GHL imza başlığını kullanan web kancası veri doğrulaması, sahte istekleri önler
• Çoğu GHL entegrasyonu dört modeli takip eder: kişi senkronizasyonu, olayla tetiklenen otomasyon, boru hattı köprüleme veya rapor toplama

---

GHL API Mimarisine Genel Bakış

GoHighLevel'in API'si (2026 itibarıyla sürüm 2), JSON istek ve yanıt gövdelerine sahip standart bir REST API'sidir. Temel URL şudur:

https://services.leadconnectorhq.com

API, kaynakları şu birincil ad alanları halinde düzenler:

API belgelerinin tamamı https://highlevel.stoplight.io/docs/integrations/ adresinde mevcuttur.

---

Kimlik Doğrulama: OAuth 2.0 Kurulumu

GHL'nin API'si tüm kimlik doğrulama için OAuth 2.0'ı kullanır. İki kimlik doğrulama bağlamı vardır:

1. Ajans Düzeyinde API Anahtarı (alt hesap yönetimi için)

Birden çok alt hesabı yöneten sunucular arası entegrasyonlar için Ajans API Anahtarını kullanın:

• Ajans Ayarları > API Anahtarları'nda oluşturulur
• Ajans düzeyindeki operasyonların kapsamı (alt hesapların oluşturulması/yönetilmesi)

2. Alt Hesap OAuth (konum başına entegrasyonlar için)

Tek bir alt hesapta çalışan entegrasyonlar için (en yaygın durum):

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

Ortak Operasyonlar İçin Gerekli Kapsamlar:

Yalnızca ihtiyacınız olan kapsamları isteyin; minimum kapsam, güvenlik için en iyi uygulamadır.

---

Temel API İşlemleri: Kişiler

Contacts API, GHL entegrasyonlarında en sık kullanılan uç noktadır.

Bir Kişi Oluşturun veya Güncelleyin:

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

Yanıt (201 Oluşturuldu):

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

E-postayla Kişi Arama (tekilleştirme için):

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

Kişi kayıtlarının yinelenmesini önlemek için oluşturmadan önce daima arama yapın.

Bir Kişiye Etiket Ekleme:

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

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

Toplu İşlemler:

GHL, POST /contacts/bulk uç noktası aracılığıyla toplu kişi oluşturmayı destekler (GHL sürümünüz için mevcut API belgelerinde doğrulayın). 500'den fazla ilgili kişinin içe aktarımında hız limitleri dahilinde kalmak için istek başına 100 ilgili kişiden oluşan gruplarla toplu uç noktayı kullanın.

---

Pipeline ve Fırsat API'si

Fırsat Yaratın:

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

Fırsatı Yeni Bir Aşamaya Taşıyın:

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

{
  "pipelineStageId": "NEW_STAGE_ID"
}

Ortak Entegrasyon Modeli: Harici CRM → GHL İşlem Hattı Senkronizasyonu

Harici bir sistemde (ör. Salesforce) bir anlaşma oluşturulduğunda entegrasyon kodunuz:

1. Kişiyi e-posta yoluyla GHL'de arar
2. Bulunamazsa kişiyi oluşturur
3. Kişiye bağlı bir GHL fırsatı yaratır
4. Çift yönlü senkronizasyon için GHL fırsat kimliğini Salesforce'ta özel bir alan olarak saklar

---

Gelen Web Kancaları: GHL'yi Harici Sistemlerden Tetikleme

Gelen web kancaları, harici sistemlerin GHL iş akışlarını başlatmasına olanak tanır. Bu, olaya dayalı entegrasyonun birincil mekanizmasıdır.

GHL'de Gelen Web Kancası Tetikleyicisi Oluşturma:

1. Otomasyon > İş Akışları > Yeni İş Akışı'na gidin
2. Tetikleyici türü olarak "Gelen Web Kancası"nı seçin
3. GHL benzersiz bir URL oluşturur: https://services.leadconnectorhq.com/hooks/YOUR_UNIQUE_HOOK_ID/webhook-trigger
4. İş akışının webhook verisinden hangi verileri kullanacağını yapılandırın

Gelen Web Kancasına Veri Gönderme:

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, tanıdığı veri alanlarından (ad, soyadı, e-posta, telefon) bir kişi oluşturur veya günceller ve customData alanlarını iş akışında değişken olarak kullanılabilir hale getirir.

Gelen Web Kancaları için Kullanım Örnekleri:

• e-Ticaret siparişi verildi → satın alma sonrası sırayı tetikleyin
• Destek bildirimi oluşturuldu → "aktif destek" etiketi ekleyin, pazarlama süreçlerini duraklatın
• Ödeme alındı → ardışık düzeni "Kazanıldı"ya taşıyın, katılım iş akışını tetikleyin
• Deneme kaydı → SaaS katılım sırasını başlatın
• Üçüncü taraf sitesinde gönderilen form → GHL CRM'ye giden yolu yakalayın

---

Giden Web Kancaları: GHL Harici Sistemleri Bildiriyor

Giden web kancaları, GHL olayları meydana geldiğinde GHL'den harici sistemlere veri gönderir.

GHL'de Giden Web Kancalarını Yapılandırma:

Ayarlar > Entegrasyonlar > Web Kancaları'na (alt hesap düzeyi) gidin veya iş akışına bir web kancası eylemi ekleyin.

GHL Yerel Giden Etkinlikleri (Ayarlar > Web Kancaları'nda mevcuttur):

• Kişi oluşturuldu
• İletişim güncellendi
• Kişi silindi
• Fırsat oluşturuldu/güncellendi/silindi
• Form gönderildi
• Randevu alındı/iptal edildi/gösterilmedi
• Konuşma mesajı (gelen)
• Çağrı başlatıldı/bitti

GHL İş Akışı Web Kancası Eylemi:

Daha ayrıntılı kontrol için iş akışına bir "Web Kancası Gönder" eylemi ekleyin. Bu, yalnızca iş akışı bu adıma ulaştığında etkinleşir ve hangi olayların harici sistemlere bildirimde bulunduğunu ve bunların hangi yükü aldığını tam olarak kontrol etmenize olanak tanır.

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

Yüke dinamik iletişim ve etkinlik verilerini dahil etmek için GHL'nin özel değer sözdizimini ({{variable.path}}) kullanın.

---

Web Kancası Güvenliği: İmza Doğrulaması

GHL, giden web kancalarını HMAC-SHA256 imzasıyla imzalar. Alıcı uç noktanız, sahte istekleri önlemek için bu imzayı doğrulamalıdır.

Doğrulama Süreci:

GHL, her webhook isteğinde bir imza başlığı içerir:

X-GHL-Signature: sha256=COMPUTED_HMAC

Sunucunuz şunları doğrular:

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

Karşılaştırma için her zaman crypto.timingSafeEqual kullanın; dize eşitliği zamanlama saldırılarına karşı savunmasızdır.

Web kancası sırrınız, GHL'nin ayarlarında web kancasını oluşturduğunuzda ayarlanır.

---

Hız Sınırlama ve En İyi Uygulamalar

GHL, API erişimine hız sınırları uygular. 2026 itibarıyla standart sınır, konum başına 10 saniyede yaklaşık 100 istektir. Bunun aşılması bir 429 Too Many Requests yanıtı döndürür.

Oran Limitleri İçinde Kalmaya Yönelik Stratejiler:

1. Üstel Gerilemeyi Uygulama:

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. Kişi Aramalarını Önbelleğe Al: Gelen her etkinlikte GHL'yi e-postayla aramayın. Redis'te veya veritabanınızda kişi kimliği aramalarını 15 dakikalık bir TTL ile önbelleğe alın. Entegrasyon akışlarının çoğu aynı kişileri tekrar tekrar içerir.

3. Toplu İletişim Güncellemeleri: Toplu veri işleminden sonra 500 kişi için özel alanları güncelliyorsanız, 500'ün tamamını aynı anda başlatmak yerine güncellemeleri toplu olarak 100 ms'lik bir gecikmeyle 10'lu gruplar halinde toplu olarak yapın.

4. Yoklama Yerine Web Kancalarını Kullanın: Değişiklikler için asla GHL'nin API'sini sorgulamayın (örneğin, yeni kişilerin oluşturulup oluşturulmadığını her dakika kontrol etme). Olaylar meydana geldiğinde bildirim almak için GHL'nin giden web kancalarını kullanın. Bu, yoklamayla ilgili oran sınırı tüketimini ortadan kaldırır.

---

Bir GHL Marketplace Uygulaması Oluşturma

Birden fazla GHL müşterisi için bir entegrasyon oluşturuyorsanız bunu bir GHL Marketplace uygulaması olarak yayınlamayı düşünün. Bu, GHL kullanıcılarının, kimlik doğrulama için OAuth'u kullanarak tek bir tıklamayla entegrasyonunuzu kurmasına olanak tanır; manuel API anahtarı paylaşımına gerek yoktur.

Pazar Yeri Listesine İlişkin Gereksinimler:

• OAuth 2.0 uygulaması
• Gizlilik politikası ve hizmet şartları URL'leri
• Uygulama simgesi ve açıklaması
• Uygulamanızın abone olduğu etkinlikler için web kancası yönetimi
• GHL inceleme ve onay süreci (genellikle 1-2 hafta)

Pazaryeri Dağıtımının Faydaları:

• GHL kullanıcıları için tek tıkla kurulum
• OAuth kimlik doğrulamayı yönetir (API anahtar yönetimi yoktur)
• GHL pazarı aracılığıyla artan keşfedilebilirlik
• GHL'nin faturalandırma altyapısı aracılığıyla entegrasyon için ücret alabilme

Birden fazla GHL ajansının veya işletmesinin kullanacağı bir entegrasyon oluşturuyorsanız bu yolu takip etmeye değer; dağıtım gücü önemlidir.

---

Ortak Entegrasyon Modelleri

Model 1: e-Ticaret Sipariş Senkronizasyonu

• Shopify sipariş web kancası → ara yazılımınız → GHL iletişim güncellemesi + etiket + iş akışı kaydı
• Ara yazılım yükü doğrular, kişileri tekilleştirir, sipariş verilerini GHL özel alanlarıyla eşler

Desen 2: ERP'den CRM Köprüsü'ne

• ERP (Odoo, QuickBooks) faturası oluşturuldu → webhook'tan ara katman yazılımına → GHL fırsatı Kazanıldı olarak işaretlendi + işlem hattı taşındı
• İki yönlü senkronizasyon: GHL boru hattı değişikliği → ERP sipariş durumu güncellemesi

Desen 3: Randevu + Saha Hizmeti Senkronizasyonu

• GHL randevusu alındı → giden webhook → FSM aracı iş yaratıyor
• FSM işi tamamlandı → GHL'ye web kancası → işlem hattını Tamamlandı'ya taşıyın + inceleme sırasını tetikleyin

Model 4: Veri Ambarı Raporlaması

• Günlük: GHL API, önceki günün bağlantılarını, fırsatlarını ve iletişim etkinliklerini çeker
• Veri ambarınızda depolanan veriler (BigQuery, Snowflake)
• Power BI veya Looker, gelişmiş platformlar arası analizler için veri ambarına bağlanır

---

Sıkça Sorulan Sorular

GHL'nin v1 ve v2 API'leri arasındaki fark nedir?

GHL'nin v2 API'si (2022-2023 civarında piyasaya sürüldü), v1'in API anahtarı kimlik doğrulamasına kıyasla OAuth 2.0 ve daha temiz bir REST tasarımı kullanır. v2 API, daha kapsamlı uç nokta kapsamına ve daha iyi belgelere sahiptir. v2 üzerine yeni entegrasyonlar kurulmalı. GHL, v1'i kullanımdan kaldırma niyetinde olduğunu belirtti ancak henüz kesin bir zaman çizelgesi belirlemedi; mevcut durum için GHL'nin geliştirici duyurularına bakın.

SMS mesajlarını programlı olarak göndermek için GHL'nin API'sini kullanabilir miyim?

Evet. Bir kişiye SMS mesajı göndermek için POST /conversations/messages uç noktasını kullanın. Konuşma kimliğine (POST /conversations/ tarafından oluşturulan) ve kişinin telefon numarasına ihtiyacınız var. Göndermeden önce kişinin SMS katılım durumuna sahip olduğundan emin olun — GHL bunu zorunlu kılar ve kapsam dışında kalan kişilere gönderim başarısız olur. Gönderen olarak gerekli type: "SMS" parametresini ve GHL konumunuzun Twilio numarasını ekleyin.

Büyük veri kümeleri için GHL API sayfalandırmasını nasıl hallederim?

GHL'nin liste uç noktaları sayfalandırılmış sonuçları döndürür. Yanıt, total, currentPage ve nextPage (veya imleç tabanlı startAfterId) içeren bir meta nesnesi içerir. nextPage null olana veya tüm kayıtları toplayana kadar sayfalar arasında yineleme yaparak sayfalandırmayı uygulayın. Büyük kişi aktarımları için (100.000'den fazla kişi), GHL'nin toplu dışa aktarma özelliğini kullanın veya veri aktarımı istemek için GHL desteğiyle iletişime geçin; çok büyük veri kümeleri için API aracılığıyla sayfalandırma işlemi yavaştır ve yoğun hız sınırı gerektirir.

GHL API entegrasyonlarını test etmek için bir korumalı alan ortamı var mı?

GHL'nin özel bir korumalı alan ortamı yoktur. Test için ayrı bir GHL deneme hesabı veya geliştirme alt hesabı kullanın. Test verilerini gerçek kişilerden ayırmak için açıkça etiketlenmiş e-postalarla (ör. [email protected]) test kişileri oluşturun. Geliştirme hesabınızı düzenli tutmak için test verilerini düzenli olarak temizleyin.

GHL kişi kimliklerini harici sistemimde saklamanın en iyi yolu nedir?

GHL contact.id'yi (benzersiz bir dize) harici sisteminizde özel bir alan olarak saklayın (örneğin, veritabanınızda bir ghl_contact_id sütunu). Bu, bir arama adımı olmadan doğrudan API çağrılarının doğru kişiye ulaşmasını sağlar. GHL'de kişi oluştururken döndürülen kimliği hemen saklayın. Çift yönlü senkronizasyon için, geriye doğru arama amacıyla sisteminizin benzersiz kimliğini de bir GHL özel alanı (örn. external_user_id) olarak saklayın.

---

Sonraki Adımlar

GoHighLevel'in API'si ve webhook sistemi, onu gerçekten genişletilebilir bir platform haline getiriyor; yalnızca kodsuz bir pazarlama aracı değil, aynı zamanda neredeyse her türlü iş sistemiyle entegre olabilen programlanabilir bir müşteri iletişim motoru. Önemli olan, başlangıçtan itibaren doğru hata yönetimi ve imza doğrulama ile temiz, iyi test edilmiş entegrasyonlar oluşturmaktır.

ECOSIRE'ın GoHighLevel hizmetleri özel API entegrasyonu geliştirmeyi içerir. Teknik ekibimiz, e-Ticaret platformları, ERP sistemleri, saha hizmeti yönetim araçları ve özel iş uygulamaları için GHL entegrasyonları oluşturur. Uygun hata yönetimi, oran limiti yönetimi ve izleme ile entegrasyonlar tasarlıyoruz.

Özel entegrasyon gereksinimlerinizi görüşmek ve özel GHL entegrasyon projeniz için teknik bir kapsam edinmek üzere ekibimizle iletişime geçin.