HubSpot entegrasyonu, web sitenizdeki formları, e-ticaret siparişlerinizi veya kendi yazılımınızı HubSpot CRM'e bağlayarak kişi, şirket ve fırsat kayıtlarının otomatik oluşmasını ve güncellenmesini sağlar. 2026'da HubSpot'un kimlik doğrulama yapısı değişti: yeni "legacy private app" oluşturma kapatıldı. Bu rehber güncel yolu anlatıyor.
İlgili içerikler: CRM entegrasyonu rehberi · Zoho CRM entegrasyonu · Bitrix24 entegrasyonu · Salesforce entegrasyonu
Kimlik Doğrulama: 2026 Değişikliği
HubSpot'un duyurusuna göre yeni legacy private app oluşturma yeni hesaplarda 28 Eylül 2026'da, mevcut hesaplarda 26 Ekim 2026'da kapatıldı. Mevcut private app'ler çalışmaya devam ediyor. Yeni entegrasyonlar için seçenekler:
| Yöntem | Ne zaman | Not |
|---|---|---|
| Service Key | Tek hesapta yalnızca REST istekleri | Webhook ve arayüz uzantısı için kullanılamaz |
| Static auth'lu proje uygulaması | Tek hesap, webhook da gerekiyorsa | Uygulama yapılandırmasında auth.type static, dağıtım private |
| OAuth uygulaması | Birden fazla müşteri hesabına dağıtım | Private dağıtımda aynı anda en fazla 10 hesap |
- Service Key oluşturma: Development, Keys, Service keys yolundan "Create service key" seçilir, ad ve scope belirlenir. Süper yöneticiler ve "Developer tools access" izni olan kullanıcılar oluşturabilir.
- Kullanım:
Authorization: Bearer pat-na1-...başlığıyla. - Döndürme: 3, 6 veya 12 ayda bir otomatik ya da elle döndürülebilir; HubSpot 6 ayda bir öneriyor. "Rotate and expire later" eski anahtarı 7 gün sonra iptal eder.
Sık kullanılan scope'lar: crm.objects.contacts.read ve .write, crm.objects.companies.write, crm.objects.deals.write, forms.
Kişi Oluşturma, Güncelleme ve Upsert
| İşlem | Uç nokta |
|---|---|
| Tekil oluşturma | POST /crm/v3/objects/contacts |
| Toplu oluşturma (en çok 100) | POST /crm/v3/objects/contacts/batch/create |
| ID ile güncelleme | PATCH /crm/v3/objects/contacts/{contactId} |
| E-posta ile güncelleme | PATCH /crm/v3/objects/contacts/{email}?idProperty=email |
| Upsert (varsa güncelle, yoksa oluştur) | POST /crm/v3/objects/contacts/batch/upsert |
curl -X POST https://api.hubapi.com/crm/v3/objects/contacts/batch/upsert \
-H "Authorization: Bearer SERVICE_KEY" \
-H "Content-Type: application/json" \
-d '{"inputs":[{"idProperty":"email","id":"ayse@ornek.com","properties":{"firstname":"Ayşe","lastname":"Yılmaz"}}]}'HubSpot tarih tabanlı API sürümlemesine geçti: yıllık Mart ve Eylül sürümleri /crm/objects/2026-09/contacts gibi yollarla yayımlanıyor ve her sürüm en az 18 ay destekleniyor. /crm/v3 yolları belgelerde yer almaya devam ediyor.
Arama (Search API)
- Aynı filtre listesi içindeki koşullar VE, ayrı filtre grupları VEYA ile birleşir.
- Hesap başına saniyede 5 istek; sorgu başına en fazla 10.000 sonuç, sayfa başına 200 kayıt.
- En fazla 5 filtre grubu, grup başına 6, toplamda 18 filtre.
- Yeni kayıtlar aramada birkaç saniye gecikmeyle görünür; kayıttan hemen sonra arama yaparak mükerrer kontrolü yapmayın, upsert kullanın.
İstek Sınırları
| Plan (private dağıtım) | 10 saniyede | Günde (hesap başına) |
|---|---|---|
| Free ve Starter | 100 | 250.000 |
| Professional | 190 | 625.000 |
| Enterprise | 190 | 1.000.000 |
Sınır aşılınca 429 döner. HubSpot hata oranının günlük isteklerin yüzde 5'inin altında tutulmasını istiyor.
Webhook ve İmza Doğrulama
- Proje uygulamalarında webhook, uygulama yapılandırmasında hedef adres ve olaylarla (ör. kayıt oluşturma, alan değişikliği) tanımlanır.
- Başarısız bildirimler 24 saat içinde 10 kereye kadar yeniden denenir; 5 saniyede yanıt verilmezse zaman aşımı sayılır.
- İstekler
X-HubSpot-Signature-v3veX-HubSpot-Request-Timestampbaşlıklarıyla gelir. İmza, yöntem, adres, gövde ve zaman damgasının uygulama gizli anahtarıyla HMAC-SHA256 ile imzalanmasıdır. 5 dakikadan eski istekleri reddedin.
Web Formu Gönderimi
Kendi formunuzu HubSpot'a göndermek için Forms API kullanılır: POST https://api.hsforms.com/submissions/v3/integration/submit/{portalId}/{formGuid}. Bu uç nokta kimlik doğrulama istemez. Gövdede alanlar (fields), sayfa bağlamı (context: çerez, sayfa adresi) ve onay seçenekleri (legalConsentOptions) gönderilir.
Veri Merkezi
HubSpot hesapları AB (Almanya) veya ABD veri merkezinde barınır; hesabın bölgesi Settings, Privacy & Consent, Data Hosting bölümünde görülür. Türkiye bölgesi yoktur.
Sık Sorulan Sorular
Yeni entegrasyonda private app kullanabilir miyim?
Yeni legacy private app artık oluşturulamıyor. Yalnızca REST için Service Key, webhook da gerekiyorsa static auth'lu proje uygulaması kullanın.
Mükerrer kişi nasıl önlenir?
batch/upsert uç noktasında idProperty olarak e-postayı kullanarak.
Arama neden 429 veriyor?
Search API'nin kendi sınırı saniyede 5 istektir ve genel sınırdan ayrıdır.
Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.