Özel İç Araçlar için HubSpot API Entegrasyonu: Node + Python Rehberi (2026)

Özel İç Araçlar için HubSpot API Entegrasyonu: Node + Python Rehberi (2026)

HubSpot API entegrasyonu'nuzu kurmak için hâlâ bir HubSpot API anahtarı mı arıyorsunuz? Aramayı bırakın. HubSpot, statik API anahtarlarını 30 Kasım 2022'de tamamen kaldırdı ve mevcut Node SDK'sı (@hubspot/api-client, artık v14) zaten bir anahtar kabul etmiyor. Tek hesaplı bir iç araç için doğru kimlik bilgisi bir private app access token'dır; bu rehber, ilk create contact çağrınızdan imza doğrulamalı bir webhook'a kadar hem Node hem Python'da gerçek bir HubSpot-iç araç senkronizasyonu kurar.

Kısa cevap: Bir HubSpot API entegrasyonu, özel bir iç aracın HubSpot'un v3 REST API'si üzerinden CRM verilerini okumasını ve yazmasını sağlar. Tek hesaplı bir iç araç için bir private app access token ile kimlik doğrulaması yapın (HubSpot, API anahtarlarını 2022'de kullanımdan kaldırdı), ardından değişiklikleri polling yerine webhook'larla gerçek zamanlı olarak senkronize edin.

Bu rehberde şunları kuracaksınız:

• Node ve Python'da private-app-token ile kimlik doğrulama ve ilk create contact çağrınız
• Bir payload'a güvenmeden önce X-HubSpot-Signature-v3'ü doğrulayan bir webhook alıcısı
• İç bir ticket veya ERP kaydına 429'a karşı dayanıklı, 100'lük batch'lerle çalışan bir senkronizasyon

HubSpot API Entegrasyonu Özel İç Araçlar için Nasıl Çalışır?

Bir HubSpot API entegrasyonu, özel bir iç aracı (bir ticket uygulaması, bir ERP, bir faturalama panosu, bir müşteri portalı) HubSpot'un CRM'ine v3 REST API'si üzerinden bağlar. Aracınız, CRM nesnelerini (contact'lar, deal'lar, company'ler veya özel nesneler) HTTPS üzerinden bir private app access token ile okur ve yazar; gerçek zamanlı değişiklikler ise webhook'lar aracılığıyla geri akar.

HubSpot'un CRM'ini, HTTP üzerinden konuştuğunuz bir veritabanı gibi düşünün. Her kayıt, bir tipi ve ID'si olan bir nesnedir (object). İnşa ettiğiniz hubspot crm api integration, iki iş yapar: veriyi HubSpot'a gönderir (bir ticket açıldığında bir contact oluşturur) ve veriyi oradan çeker (iç panonuz render edildiğinde bir deal okur).

Senkronizasyon iki yönden birinde çalışır. Bir tek yönlü senkronizasyon, değişiklikleri HubSpot'tan aracınıza ya da aracınızdan HubSpot'a kopyalar. Bir iki yönlü senkronizasyon ise her ikisini de yapar ve ileride ele alacağımız bir loop koruması gerektirir. HubSpot'a her dakika "yeni bir şey var mı?" diye sormak (polling) yerine, bir webhook kaydedersiniz; böylece bir kayıt değiştiği anda HubSpot size haber verir.

Verilerinizin tamamına sahip olmayı, barındırılan bir CRM'i entegre etmeye tercih ediyorsanız, bir açık kaynaklı CRM'i kendiniz barındırmak, karar vermeden önce değerlendirmeye değer farklı bir yoldur. Ama HubSpot zaten sizin tek doğru kaynağınızsa (source of truth), diğer her şeyin onunla konuşma şekli bu API'dir.

Tek hesaplı bir iç araç için OAuth'a ya da bir app-marketplace listelemesine ihtiyacınız yok. Bir private app token ve bir webhook, entegrasyonun tamamı için yeterlidir.

2026'da Kimlik Doğrulama: HubSpot API Anahtarı Neden Artık Yok?

Tek hesaplı bir iç araçta HubSpot API kimlik doğrulaması için bir private app access token kullanın. Bu, HubSpot hesabınızda bir kez oluşturduğunuz, aracınızın dokunduğu nesnelere tam olarak kapsamlandırılmış (scoped) statik bir bearer token'dır. Ne bir yenileme akışı ne de bir son kullanma tarihi vardır. OAuth, genel ve çok hesaplı uygulamalar için vardır; operasyon ekibinizin iç kullanım için çalıştırdığı pano için değil.

Private App Token'a Karşı Kullanımdan Kaldırılan API Key

İşte bu aramaya (SERP) düşen geliştiricilerin yarısını tökezleten can sıkıcı nokta. HubSpot, API anahtarlarını 30 Kasım 2022'de kullanımdan kaldırdı ve artık tamamen desteklenmiyorlar. Otomatik tamamlama hâlâ "hubspot api key" önerir, çünkü alışkanlık henüz buna yetişemedi, ama alınacak bir anahtar yok. Bunun yerine bir hubspot private app kullanın: Settings'te oluşturun, ihtiyaç duyduğu scope'ları verin ve access token'ı Auth sekmesinden kopyalayın. HubSpot'un private apps genel bakışı kurulumu ayrıntılı olarak anlatıyor.

Token'ın kendisiyle ilgili iki kural var. En az yetki (least privilege) ilkesini uygulayın: aracınız yalnızca deal'ları okuyup contact'ları yazıyorsa, crm.objects.contacts.write ve crm.objects.deals.read'i isteyin, fazlasını değil. Ve token'ı bir ortam değişkeninde veya bir secret manager'da tutun; Authorization: Bearer header'ıyla gönderin, asla koda gömmeyin, asla tarayıcıya göndermeyin.

Sonuç basit. Bir iç araç için private app access token kullanın. OAuth'a yalnızca bu araç ileride diğer şirketlerin kendi portallarına kurduğu genel, çok hesaplı bir uygulamaya dönüşürse başvurun.

İlk HubSpot API Çağrınız: Node ve Python'da Contact Oluşturmak

Klasik ilk çağrı create contact'tır ve resmi SDK'lar bunu birkaç satıra indirir. İstemciyi (client) kurun, ortam değişkeninden aldığınız private app token'ınızla başlatın, ardından bir contact oluşturup bir deal'ı geri okuyun. Bu, company'ler, ticket'lar ve hubspot custom objects api çağrıları için de tekrar kullanacağınız aynı örüntüdür; yalnızca nesne tipi değişir.

İşte @hubspot/api-client (v14) ile Node versiyonu:

// npm i @hubspot/api-client   (v14.x)
import { Client } from "@hubspot/api-client";

// Private app token bir secret manager'dan veya env değişkeninden gelir, asla koda gömülmez
const hubspot = new Client({ accessToken: process.env.HUBSPOT_PRIVATE_APP_TOKEN });

// Bir contact oluştur
const { id } = await hubspot.crm.contacts.basicApi.create({
  properties: {
    email: "[email protected]",
    firstname: "Ada",
    lastname: "Lovelace",
    lifecyclestage: "lead",
  },
  associations: [],
});
console.log("Created contact", id);

// ID'ye göre bir deal oku
const deal = await hubspot.crm.deals.basicApi.getById(
  "1234567890",
  ["dealname", "amount", "dealstage"],
);
console.log(deal.properties.dealname, deal.properties.amount);

Ve aynısının hubspot-api-client (v12) ile Python'daki hâli:

# pip install hubspot-api-client   (v12.x)
import os
from hubspot import HubSpot
from hubspot.crm.contacts import SimplePublicObjectInputForCreate

# Private app token ortam değişkeninden gelir, kaynak koddan değil
client = HubSpot(access_token=os.environ["HUBSPOT_PRIVATE_APP_TOKEN"])

# Bir contact oluştur
contact = client.crm.contacts.basic_api.create(
    simple_public_object_input_for_create=SimplePublicObjectInputForCreate(
        properties={
            "email": "[email protected]",
            "firstname": "Ada",
            "lastname": "Lovelace",
            "lifecyclestage": "lead",
        }
    )
)
print("Created contact", contact.id)

# ID'ye göre bir deal oku
deal = client.crm.deals.basic_api.get_by_id(
    deal_id="1234567890",
    properties=["dealname", "amount", "dealstage"],
)
print(deal.properties["dealname"], deal.properties["amount"])

Profesyonel ipucu: önce üretime (production) değil, her zaman bir HubSpot developer sandbox'ına karşı test edin. Üretimde hatalı bir create çağrısı, satış ekibinizin temizlemesi gereken gerçek çöp kayıtlar bırakır. Token, scope'lar ve nesne modeli sandbox'ta birebir aynı şekilde davranır.

HubSpot'u Bir İç Araçla Gerçek Zamanlı Nasıl Senkronize Edersiniz?

Polling değil, webhook kullanın. Private app'inizde önemsediğiniz nesne ve event için bir webhook subscription'ı kaydedin (örneğin deal.propertyChange), bunu kendi barındırdığınız bir HTTPS endpoint'ine yönlendirin; eşleşen bir değişiklik olduğu anda HubSpot size küçük bir JSON dizisi POST eder. Polling'e yalnızca izlemek istediğiniz şey için bir subscription mevcut değilse başvurun.

Kazanç, verimlilik. Polling her dakika "yeni bir şey var mı?" diye sorar ve bunu yaparken rate limit'inizi tüketir; bir webhook ise yalnızca bir deal değiştiği anda size haber verir. Bu fark ölçek büyüdükçe önem kazanır ve webhook'lar artık egzotik değil, yaygın: Postman'ın 2025 API Durumu Raporu, 5.700'den fazla geliştiriciyle yapılan bir ankette, ekiplerin yaklaşık yarısının webhook'lara güvendiğini ortaya koydu.

Subscription'ı private app'inizin Webhooks sekmesi altında kaydedin, hedef URL'yi ayarlayın ve event'leri seçin. HubSpot, her biri subscriptionType, objectId ve neyin değiştiğini taşıyan bir event nesneleri dizisi gönderir. İşte Express ile Node'da bir alıcı (receiver) taslağı:

import express from "express";

const app = express();
// Ham gövdeyi (raw body) yakala: imzayı doğrulamak için bir sonraki bölümde tam byte dizisine ihtiyacınız var
app.use(express.json({
  verify: (req, _res, buf) => { req.rawBody = buf.toString("utf8"); },
}));

// HubSpot bu URL'ye bir events dizisi POST eder
app.post("/webhooks/hubspot", (req, res) => {
  const events = req.body; // [{ subscriptionType: "deal.propertyChange", objectId: 1234, ... }]
  for (const event of events) {
    console.log("HubSpot event:", event.subscriptionType, event.objectId);
    // Bu payload'a henüz güvenmeyin. Bir sonraki bölüm, işlem yapmadan önce onu doğrular.
  }
  res.sendStatus(200);
});

app.listen(3000, () => console.log("Listening on :3000"));

İşte burada birlikte inşa ettiğimiz şey gerçekleşiyor. Diyelim ki bir deal'ı küçük bir üreticinin ERP kaydına senkronize ediyorsunuz: webhook tetiklenir, handler'ınız eşleşen ERP ticket'ını oluşturur veya günceller ve operasyon ekibiniz HubSpot'a hiç dokunmadan değişikliği görür. Bu, bir sesli asistanı (voice agent) bir CRM'e senkronize etmek için kullandığımız yaklaşımla aynıdır; tek fark, tetikleyicinin bir telefon görüşmesi yerine bir property değişikliği olmasıdır. Bir uyarı: yukarıdaki taslak, kendisine POST edilen her şeye güvenir. Canlıya çıkmadan önce bunu düzeltin.

Webhook İmzalarını Doğrulamak (v3): Sahte Bir Payload'a Asla Güvenmeyin

Gelen her webhook'u v3 imzasıyla doğrulayın. HubSpot, her isteği app secret'ınızla imzalar ve iki header gönderir: X-HubSpot-Signature-v3 ve X-HubSpot-Request-Timestamp. 5 dakikadan eski olan her şeyi reddedin, kaynak dizesini (source string) method + tam URL + raw body + timestamp olarak yeniden oluşturun, bunu app secret ile HMAC-SHA256'dan geçirin, base64 ile kodlayın ve sabit zamanlı (constant-time) olarak karşılaştırın.

Bunu atlarsanız, webhook URL'nizi tahmin eden herkes sahte bir deal güncellemesi üretebilir. Doğrulama isteğe bağlı değildir. HubSpot'un isteklerin doğrulanması dokümanı ve v3 imzalar changelog'u tam tarifi adım adım anlatıyor. İşte doğrudan kullanılabilir bir Express middleware'i olarak:

import crypto from "crypto";

const CLIENT_SECRET = process.env.HUBSPOT_APP_SECRET; // private app ayarlarınızdan alınır
const MAX_AGE_MS = 5 * 60 * 1000; // 5 dakikadan eski olan her şeyi reddet

export function validateHubSpotSignature(req, res, next) {
  const signature = req.header("X-HubSpot-Signature-v3");
  const timestamp = req.header("X-HubSpot-Request-Timestamp");

  // 1. Bayat (stale) istekleri reddet (replay koruması)
  if (!signature || !timestamp || Date.now() - Number(timestamp) > MAX_AGE_MS) {
    return res.sendStatus(401);
  }

  // 2. Kaynak dizesini (source string) birebir yeniden oluştur: method + tam URL + raw body + timestamp
  const uri = `https://${req.get("host")}${req.originalUrl}`;
  const source = `${req.method}${uri}${req.rawBody}${timestamp}`;

  // 3. App secret ile HMAC-SHA256, base64 kodlamalı
  const hash = crypto
    .createHmac("sha256", CLIENT_SECRET)
    .update(source, "utf8")
    .digest("base64");

  // 4. Header ile sabit zamanlı (constant-time) karşılaştırma
  const expected = Buffer.from(hash);
  const received = Buffer.from(signature);
  if (expected.length !== received.length ||
      !crypto.timingSafeEqual(expected, received)) {
    return res.sendStatus(401);
  }
  next();
}

Aynı kontrolün bir Python fonksiyonu hâli, böylece her iki teknoloji yığını da kapsanmış olur:

import base64
import hashlib
import hmac
import os
import time

CLIENT_SECRET = os.environ["HUBSPOT_APP_SECRET"].encode("utf-8")
MAX_AGE_MS = 5 * 60 * 1000  # 5 dakika

def is_valid_signature(method, uri, body, signature, timestamp):
    # 1. Bayat istekleri reddet
    if not signature or not timestamp:
        return False
    if int(time.time() * 1000) - int(timestamp) > MAX_AGE_MS:
        return False

    # 2. method + tam URL + raw body + timestamp
    source = f"{method}{uri}{body}{timestamp}".encode("utf-8")

    # 3. HMAC-SHA256, base64
    digest = hmac.new(CLIENT_SECRET, source, hashlib.sha256).digest()
    expected = base64.b64encode(digest).decode("utf-8")

    # 4. Sabit zamanlı karşılaştırma
    return hmac.compare_digest(expected, signature)

İnsanlara bir öğleden sonrasını kaybettiren can sıkıcı nokta şu: HubSpot, tam hedef URL'yi imzalar; scheme, host ve path birlikte. Bir proxy, bir load balancer veya bir ngrok tüneli arkasında, req.get("host") HubSpot'un imzaladığı genel (public) host yerine iç host'u bildirebilir. Meşru olduğundan emin olduğunuz bir payload'da doğrulama sürekli başarısız oluyorsa, yeniden oluşturduğunuz tam URI'yi loglayın ve karakter karakter genel webhook URL'nizle karşılaştırın.

Rate Limit'ler, 429'lar ve Batch API: Üretimde Neler Çalıştırdık

Private app'ler, günlük 250.000 ile 1.000.000 arasında bir üst sınırla birlikte saniyede yaklaşık 10 istek alır (Free/Starter'da 10 saniyede 100, Pro/Enterprise'da 10 saniyede 190). Tuzak şu: CRM Search ayrıca saniyede 4 istek ile sınırlıdır ve batch endpoint'leri istek başına en fazla 100 kayıt kabul eder. HubSpot'un kullanım kılavuzu katmanları (tiers) listeliyor.

İşte teorinin, kırmızıya boyanmış bir staging panosuyla tanıştığı yer. Bu bahar bir backfill sırasında, bir iç ticket aracından HubSpot'a yaklaşık 8.000 mevcut kaydı ittik ve her birini bir CRM Search sorgusuyla zenginleştirdik. Node tarafında @hubspot/api-client v14, Python tarafındaki bir zenginleştirme (enrichment) worker'ında ise hubspot-api-client v12 çalıştırıyorduk. Toplu yazmalar (bulk writes) sorunsuzdu. Search çağrıları bir dakika içinde çöktü, çünkü worker'ımız, ayrıca bütçelemediğimiz sabit 4 istek/sn tavanına karşı yaklaşık 15 istek/sn hızında Search ateşliyordu.

İki değişiklik bunu düzeltti. İlki, X-HubSpot-RateLimit-* response header'larını okuyan ve bir 429'da geri çekilen (backs off) bir retry wrapper'ı:

// Herhangi bir HubSpot çağrısını sarmalar; 429 durumunda üstel geri çekilmeyle (exponential backoff) yeniden dener
async function withRetry(fn, maxRetries = 5) {
  let attempt = 0;
  while (true) {
    try {
      return await fn();
    } catch (err) {
      const status = err.code ?? err.response?.status;
      if (status !== 429 || attempt >= maxRetries) throw err;

      // Header mevcutsa HubSpot'un reset penceresine uy
      const headers = err.response?.headers ?? {};
      const resetMs = Number(headers["x-hubspot-ratelimit-interval-milliseconds"]) || 0;
      const backoff = Math.max(resetMs, 2 ** attempt * 500); // 0.5s, 1s, 2s, 4s...

      console.warn(`429 hit, retry ${attempt + 1} in ${backoff}ms`);
      await new Promise((r) => setTimeout(r, backoff));
      attempt++;
    }
  }
}

İkincisi, kayıtları teker teker yazmayı bıraktık. Batch endpoint'i, POST /crm/v3/objects/{objectType}/batch/create başına 100 kayda kadar alıyor; bu yüzden backfill'i 8.000 tekil POST yerine 80 batch çağrısına böldük (chunk):

// HubSpot batch endpoint'leri istek başına en fazla 100 kayıt kabul eder
function chunk(arr, size = 100) {
  const out = [];
  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size));
  return out;
}

// POST /crm/v3/objects/contacts/batch/create, seferde 100'lük parçalara (chunk) bölünür
async function batchCreateContacts(records) {
  for (const group of chunk(records, 100)) {
    const inputs = group.map((r) => ({
      properties: { email: r.email, firstname: r.firstName, lastname: r.lastName },
      associations: [],
    }));
    await withRetry(() => hubspot.crm.contacts.batchApi.create({ inputs }));
    console.log(`Wrote ${group.length} contacts`);
  }
}

Search worker'ını 4 istek/sn ile sınırlamak ve yazmaları batch'lemek, retry'lara boğulan bir çalıştırmayı sessizce tamamlanan bir çalıştırmaya dönüştürdü. Bu bölümden tek bir sayı hatırlayacaksanız, 4 olsun: CRM Search tavanı, üretimde asıl ısıran sınırdır ve her derleme (roundup) yazısının bahsetmeyi unuttuğu şeydir. Bu arada, eski "contact'lar için 10" batch tavanı da artık yok; güncel değer tüm nesne tipleri için 100.

İki Yönlü Gitmek: Sonsuz Döngüye Girmeden Değişiklikleri HubSpot'a Geri Yazmak

Bir iki yönlü senkronizasyon, değişiklikleri okumanın yanı sıra iç aracınızdan HubSpot'a da geri yazar. Tehlike bir feedback loop'udur: geri yazmanız, handler'ınızı tetikleyen webhook'un ta kendisini tetikler, o da tekrar yazar, sonsuza dek. Bunu bir idempotency key (zaten uyguladığınız değişiklikleri atlar) ve bir source flag (kendi aracınızın tetiklediği gelen event'leri yok sayar) ile önleyin.

const processed = new Set(); // production'da Redis veya benzersiz (unique) bir DB kısıtı kullanın

async function writeBackToHubSpot(record) {
  // Dedup key: object id + uygulanacak değişikliğin hash'i
  const key = `${record.id}:${record.updatedHash}`;
  if (processed.has(key)) return; // bu tam değişiklik zaten senkronize edildi
  processed.add(key);

  await withRetry(() =>
    hubspot.crm.contacts.basicApi.update(record.id, {
      // Kaynağı etiketle ki ortaya çıkan webhook kendi alıcımız tarafından yok sayılsın
      // (gelen bir event üzerinde işlem yapmadan önce source: "internal-tool" kontrolü yapın)
      properties: { internal_status: record.status, last_sync_source: "internal-tool" },
    })
  );
}

Bu örüntü küçük, ama onu atlamak, bir senkronizasyonun yazma hacminizi bir gecede sessizce ikiye katlamasının tam olarak yoludur. Veri her iki yönde de temizlendikten sonra, ekipler genellikle bunu aşağı akışta bir AI SDR pipeline'ına veya bir raporlama katmanına besler. İki yönlü senkronizasyona ikinci bir bakış istiyorsanız, Nango'nun HubSpot entegrasyon eğitimi sağlam, yalnızca Node'a özgü bir referanstır; ancak loop koruması fikrini kendiniz taşımanız gerekecek.

Bunu Kendiniz mi İnşa Etmelisiniz, Yoksa Bir Entegrasyon Ortağı mı Tutmalısınız?

Senkronizasyon küçük, istikrarlı ve sahiplenilmiş olduğunda kendi içinizde inşa edin: tek yönlü bir akış, bir avuç nesne ve HubSpot'un yılda kabaca iki kez gelen breaking change'lerini karşılayabilecek bir mühendis. Çift yönlü senkronizasyona, özel nesne (custom-object) modellemesine ihtiyacınız olduğunda ya da ekipte devam eden bakımı sahiplenecek kimse olmadığında bir ortak tutun. Belirleyici faktör nadiren ilk inşa aşamasıdır; bir yıl sonra kimin buna göz kulak olacağıdır.

İşte dürüst bir kontrol listesi. Şu durumda kendiniz inşa edin: yön tek yönlüyse, standart nesneleri senkronize ediyorsanız, bir webhook endpoint'ini barındırabilecek bir geliştiriciniz varsa ve bir payload başarısız olmaya başladığında bunu fark edecek biri varsa. Yukarıdaki her şey sizin planınızdır.

Şu durumda bir ortak tutun: birden fazla nesne genelinde loop korumalı çift yönlü senkronizasyona ihtiyacınız varsa, tipli association'larla özel nesneler modelliyorsanız, birden fazla sistemi birbirine bağlıyorsanız (HubSpot artı bir ERP artı faturalama) ya da bunu sürdürecek kişi zaten kapasitesinin üzerindeyse. HubSpot, yılda yalnızca yaklaşık iki kez breaking change içeren tarih bazlı API versiyonlaması kullanır; bu, biri en yoğun haftanızda gelip de kimse sahiplenmeyene kadar zararsız görünür. İç entegrasyonları sessizce batıran şey ilk deploy değil, bu bakım kuyruğudur. Bunu sahiplenmek istemiyorsanız, işte tam da burada özel CRM entegrasyon hizmetlerimiz devreye giriyor.

Önemli Çıkarımlar

• Artık bir HubSpot API anahtarı yok. Tek hesaplı bir iç araç için bir private app access token kullanın; OAuth yalnızca genel, çok hesaplı uygulamalar içindir.
• Bir webhook payload'ına güvenmeden önce her zaman X-HubSpot-Signature-v3'ü doğrulayın. Kaynak dizesini tam hedef URL ile yeniden oluşturun.
• 4 istek/sn CRM Search sınırına uyun ve büyük yazmaları bir 429 backoff'uyla 100'lük parçalar hâlinde batch'leyin.
• Gerçek zamanlı senkronizasyon için polling yerine webhook'ları tercih edin; bir HubSpot entegrasyonu, daha geniş bir işletmeler için yapay zeka araçları yığınının yalnızca bir parçasıdır.

Bakım tarafında takıldınız mı, ya da canlıya almadan önce ikinci bir göz mü istiyorsunuz? Ücretsiz bir entegrasyon danışmanlığı ayırtın. Ne olursa olsun bir baskı yok; yukarıdaki kod zaten sizin, çalıştırmak size kalmış.

Sıkça Sorulan Sorular

2026'da hâlâ bir HubSpot API anahtarına ihtiyacım var mı?

Hayır. HubSpot, statik API anahtarlarını 30 Kasım 2022'de kullanımdan kaldırdı ve artık tamamen desteklenmiyorlar. Otomatik tamamlama alışkanlıktan hâlâ "hubspot api key" önerir, ama alınacak hiçbir şey yok. Tek hesaplı bir iç araç için Settings'te bir private app oluşturun ve bunun yerine onun access token'ını kullanın.

HubSpot'ta private app token ile OAuth arasındaki fark nedir?

Bir private app access token, tek bir HubSpot hesabı için statik bir kimlik bilgisidir; son kullanma tarihi ve yenileme akışı yoktur, bir iç araç için idealdir. OAuth 2.0 ise diğer şirketlerin kendi portallarına kurduğu genel, çok hesaplı uygulamalar içindir; token'ları yaklaşık altı saatte sona erer ve bir yenileme döngüsü gerektirir.

HubSpot'un 2026'daki API rate limit'leri nelerdir?

Private app'ler saniyede yaklaşık 10 istek alır (Free/Starter'da 10 saniyede 100, Pro/Enterprise'da 190), günlük üst sınır 250.000 ile 1.000.000 arasındadır. CRM Search API'si ayrıca saniyede 4 istek ile sınırlıdır ve batch endpoint'leri istek başına en fazla 100 kayıt kabul eder.

Bir HubSpot webhook imzasını nasıl doğrularım?

v3 tarifini kullanın: X-HubSpot-Request-Timestamp'i beş dakikadan eski olan istekleri reddedin, ardından method artı tam hedef URL artı raw body artı timestamp'ten oluşan bir kaynak dizesi (source string) oluşturun. Bunu app secret'ınızla HMAC-SHA256'dan geçirin, sonucu base64 ile kodlayın ve X-HubSpot-Signature-v3 ile sabit zamanlı olarak karşılaştırın.

Hangi HubSpot SDK'sını kullanmalıyım, Node mu Python mu?

İkisi de resmi ve bakımı yapılıyor. Node @hubspot/api-client (v14) kullanır, Python ise hubspot-api-client (v12) kullanır. İkisi de aynı v3 CRM nesne modelini sunar, bu yüzden yığınınıza uyanı seçin. Bu rehber, her iki dilde de birebir aynı kimlik doğrulama ve imza doğrulama kodunu sunuyor.

HubSpot'u özel bir iç araçla gerçek zamanlı nasıl senkronize ederim?

Private app'inizde önemsediğiniz nesne ve event için bir webhook subscription'ı kaydedin, ardından eşleşen bir değişiklik olduğunda HubSpot'un POST ettiği bir HTTPS endpoint'i barındırın. İmzayı doğrulayın, ardından değişikliği iç aracınıza yazın. Polling'e yalnızca ihtiyacınız olan şeyi kapsayan bir webhook subscription'ı yoksa başvurun.

HubSpot Service Key nedir ve kullanmalı mıyım?

Service Key, HubSpot'un Şubat 2026'da genel betaya aldığı, hesap düzeyinde ve yalnızca veriye yönelik bir kimlik bilgisidir. Yalnızca veriyle çalışan sunucu tarafı işleri hedefler. Bugün standart bir iç araç için, private app access token hâlâ daha güvenli, daha iyi dokümante edilmiş varsayılan seçenektir; Service Key'leri betadan çıkana kadar beta olarak değerlendirin.

Üretime dokunmadan bir HubSpot entegrasyonunu test edebilir miyim?

Evet. Bir HubSpot developer sandbox'ı oluşturun ve private app token'ınızı buna yönlendirin. Scope'lar, nesne modeli, webhook'lar ve rate limit'ler üretimdekiyle aynı şekilde davranır; böylece satış ekibinizin daha sonra temizlemesi gereken çöp kayıtlar bırakmadan test contact'ları oluşturabilir ve webhook'lar tetikleyebilirsiniz.

HubSpot batch API'si tek seferde kaç kayıt alabilir?

Batch endpoint'leri (POST /crm/v3/objects/{objectType}/batch/create ve update, upsert benzerleri) istek başına en fazla 100 kayıt kabul eder. Daha büyük payload'ları 100'lük gruplara bölün (chunk). Bazı eğitimlerin hâlâ andığı eski "contact'lar için 10 kayıt" tavanı kaldırıldı; güncel değer tüm nesne tipleri için 100'dür.

Bunu kendim mi inşa etmeliyim, yoksa bir ajans mı tutmalıyım?

Senkronizasyon tek yönlüyse, standart nesneler kullanıyorsa ve HubSpot'un yılda iki kez gelen breaking change'lerini karşılayabilecek bir sahibi varsa kendi içinizde inşa edin. Çift yönlü senkronizasyon, özel nesne modellemesi için ya da bakımı kimse sahiplenemiyorsa bir ortak tutun. İlk deploy kolaydır; asıl maliyet ondan sonraki bir yıllık bakımdır.