Integracja z API HubSpot dla niestandardowych narzędzi wewnętrznych: Przewodnik Node + Python (2026)

Integracja z API HubSpot dla niestandardowych narzędzi wewnętrznych: Przewodnik Node + Python (2026)

Nadal szukasz klucza API HubSpot, aby podpiąć swoją integrację z API HubSpot? Przestań szukać. HubSpot wycofał statyczne klucze API 30 listopada 2022 roku, a obecny zestaw SDK dla Node (@hubspot/api-client, obecnie w wersji 14) i tak ich nie akceptuje. Właściwym poświadczeniem dla jednokontowego narzędzia wewnętrznego jest token dostępu prywatnej aplikacji, a ten przewodnik pokazuje, jak zbudować rzeczywistą synchronizację HubSpot-z-narzędziem-wewnętrznym zarówno w Node, jak i w Pythonie – od pierwszego wywołania create contact po webhook z walidacją podpisu.

Krótka odpowiedź: Integracja z API HubSpot pozwala niestandardowemu narzędziu wewnętrznemu odczytywać i zapisywać dane CRM za pośrednictwem REST API v3 firmy HubSpot. W przypadku jednokontowego narzędzia wewnętrznego uwierzytelniaj się za pomocą tokena dostępu prywatnej aplikacji (HubSpot wycofał klucze API w 2022 roku), a następnie synchronizuj zmiany w czasie rzeczywistym przy użyciu webhooków zamiast odpytywania (polling).

Oto, co zbudujesz:

• Autoryzację tokenem prywatnej aplikacji oraz pierwsze wywołanie create contact w Node i Pythonie
• Odbiornik webhooków, który waliduje nagłówek X-HubSpot-Signature-v3 przed zaufaniem ładunkowi danych
• Bezpieczną obsługę błędów 429 i wsadową synchronizację (batch-100) do wewnętrznego systemu zgłoszeń lub rekordów ERP

Jak działa integracja z API HubSpot w przypadku niestandardowych narzędzi wewnętrznych?

Integracja z API HubSpot łączy niestandardowe narzędzie wewnętrzne (aplikację do obsługi zgłoszeń, system ERP, panel rozliczeniowy, portal klienta) z CRM firmy HubSpot poprzez jej REST API v3. Twoje narzędzie odczytuje i zapisuje obiekty CRM (kontakty, oferty, firmy lub obiekty niestandardowe) przez HTTPS, używając tokena dostępu prywatnej aplikacji, a zmiany w czasie rzeczywistym są przesyłane z powrotem przez webhooki.

Traktuj CRM HubSpota jako bazę danych, z którą komunikujesz się przez HTTP. Każdy rekord to obiekt posiadający typ i identyfikator. Budowana przez Ciebie hubspot crm api integration wykonuje dwa zadania: wypycha dane do HubSpota (tworzy kontakt po otwarciu zgłoszenia) i pobiera je z niego (odczytuje ofertę podczas renderowania wewnętrznego panelu).

Synchronizacja odbywa się w jednym z dwóch kierunków. Synchronizacja jednokierunkowa kopiuje zmiany z HubSpota do Twojego narzędzia lub z Twojego narzędzia do HubSpota. Synchronizacja dwukierunkowa robi obie te rzeczy i wymaga mechanizmu ochrony przed pętlami, o czym wspomnimy później. Zamiast pytać HubSpota „czy jest coś nowego?” co minutę (odpytywanie), rejestrujesz webhook, dzięki czemu HubSpot informuje Cię natychmiast po zmianie rekordu.

Jeśli wolisz mieć pełną własność nad danymi niż integrować hostowany CRM, self-hosting CRM open-source jest inną ścieżką, którą warto rozważyć przed podjęciem decyzji. Ale jeśli HubSpot jest już Twoim źródłem prawdy, API jest sposobem, w jaki wszystko inne się z nim komunikuje.

W przypadku jednokontowego narzędzia wewnętrznego nie potrzebujesz OAuth ani listingu w marketplace aplikacji. Token prywatnej aplikacji i webhook to cała integracja.

Uwierzytelnianie w 2026 roku: Dlaczego nie ma już klucza API HubSpot

Do uwierzytelniania API HubSpot w jednokontowym narzędziu wewnętrznym używaj tokena dostępu prywatnej aplikacji. Jest to statyczny token bearer, który generujesz raz w swoim koncie HubSpot, z uprawnieniami ograniczonymi dokładnie do obiektów, których dotyka Twoje narzędzie. Nie ma tu procesu odświeżania ani wygaśnięcia. OAuth istnieje dla publicznych aplikacji obsługujących wiele kont, a nie dla panelu, z którego korzysta wewnętrznie Twój zespół operacyjny.

Token prywatnej aplikacji a wycofany klucz API

Oto pułapka, na którą wpada połowa programistów trafiających na tę stronę wyników wyszukiwania. HubSpot wycofał klucze API 30 listopada 2022 roku i obecnie nie są one w ogóle wspierane. Autouzupełnianie nadal sugeruje „hubspot api key”, ponieważ nawyki nie nadążają za zmianami, ale nie ma już klucza do pobrania. Sięgnij po prywatną aplikację hubspot: utwórz ją w Ustawieniach, przyznaj wymagane zakresy uprawnień i skopiuj token dostępu z zakładki Auth. Przegląd prywatnych aplikacji HubSpota omawia konfigurację.

Dwie zasady dotyczące samego tokena. Przyznaj najmniejsze możliwe uprawnienia: jeśli Twoje narzędzie tylko odczytuje oferty i zapisuje kontakty, poproś o crm.objects.contacts.write oraz crm.objects.deals.read, nic więcej. I przechowuj token w zmiennej środowiskowej lub menedżerze sekretów, wysyłany w nagłówku Authorization: Bearer, nigdy nie zakodowany na sztywno i nigdy nie wysyłany do przeglądarki.

Werdykt jest prosty. Dla narzędzia wewnętrznego używaj tokena dostępu prywatnej aplikacji. Sięgaj po OAuth tylko wtedy, gdy stanie się to później publiczną, wielokontową aplikacją instalowaną przez inne firmy w ich własnych portalach.

Twoje pierwsze wywołanie API HubSpot: Tworzenie kontaktu w Node i Pythonie

Kanonicznym pierwszym wywołaniem jest create contact, a oficjalne zestawy SDK sprawiają, że sprowadza się to do kilku linijek. Zainstaluj klienta, zainicjuj go swoim tokenem prywatnej aplikacji pobranym ze zmiennych środowiskowych, a następnie utwórz kontakt i odczytaj ofertę. To ten sam wzorzec, którego będziesz używać dla firm, zgłoszeń i wywołań hubspot custom objects api, zmienia się tylko typ obiektu.

Oto wersja dla Node z użyciem @hubspot/api-client (v14):

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

// Private app token from a secret manager or env var, never hard-coded
const hubspot = new Client({ accessToken: process.env.HUBSPOT_PRIVATE_APP_TOKEN });

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

// Read a deal by ID
const deal = await hubspot.crm.deals.basicApi.getById(
  "1234567890",
  ["dealname", "amount", "dealstage"],
);
console.log(deal.properties.dealname, deal.properties.amount);

I to samo w Pythonie z użyciem hubspot-api-client (v12):

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

# Private app token from the environment, not source control
client = HubSpot(access_token=os.environ["HUBSPOT_PRIVATE_APP_TOKEN"])

# Create a contact
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)

# Read a deal by ID
deal = client.crm.deals.basic_api.get_by_id(
    deal_id="1234567890",
    properties=["dealname", "amount", "dealstage"],
)
print(deal.properties["dealname"], deal.properties["amount"])

Wskazówka: testuj na piaskownicy developerskiej HubSpota, nigdy najpierw na produkcji. Błędne wywołanie tworzące na produkcji pozostawia prawdziwe śmieciowe rekordy, które musi posprzątać Twój zespół sprzedażowy. Token, zakresy uprawnień i model obiektów zachowują się identycznie w piaskownicy.

Jak synchronizować HubSpot z narzędziem wewnętrznym w czasie rzeczywistym?

Używaj webhooków, a nie odpytywania. Zarejestruj subskrypcję webhooka w swojej prywatnej aplikacji dla obiektu i zdarzenia, które Cię interesują (np. deal.propertyChange), wskaż ją na endpoint HTTPS, który hostujesz, a HubSpot wyśle Ci małą tablicę JSON w momencie wystąpienia pasującej zmiany. Odpytuj tylko wtedy, gdy nie istnieje subskrypcja dla tego, co musisz obserwować.

Zyskiem jest wydajność. Odpytywanie pyta „czy jest coś nowego?” co minutę i marnuje przy tym Twój limit szybkości; webhook po prostu informuje Cię w momencie zmiany oferty. Ta różnica ma znaczenie w skali, a webhooki są obecnie mainstreamem, a nie egzotyką: Raport State of the API Report 2025 firmy Postman, będący ankietą wśród ponad 5700 deweloperów, wykazał, że około połowa zespołów polega na nich.

Zarejestruj subskrypcję w zakładce Webhooks swojej prywatnej aplikacji, ustaw docelowy URL i wybierz zdarzenia. HubSpot wysyła tablicę obiektów zdarzeń, z których każdy zawiera subscriptionType, objectId i informacje o tym, co się zmieniło. Oto szkielet odbiornika w Node z Express:

import express from "express";

const app = express();
// Capture the raw body: you need the exact bytes to validate the signature next
app.use(express.json({
  verify: (req, _res, buf) => { req.rawBody = buf.toString("utf8"); },
}));

// HubSpot POSTs an array of events to this URL
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);
    // Do NOT trust this payload yet. The next section validates it before we act.
  }
  res.sendStatus(200);
});

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

Tutaj praktyczne podejście staje się rzeczywistością. Powiedzmy, że synchronizujesz ofertę z rekordem ERP małego producenta: webhook uruchamia się, Twój handler tworzy lub aktualizuje pasujące zgłoszenie w ERP, a Twój zespół operacyjny widzi zmianę bez dotykania HubSpota. To to samo podejście w czasie rzeczywistym, którego używamy do synchronizacji agenta głosowego z CRM, tylko wyzwalaczem jest zmiana właściwości, a nie połączenie telefoniczne. Jedno ostrzeżenie: powyższy szkielet ufa wszystkiemu, co zostanie do niego wysłane metodą POST. Napraw to przed przejściem na produkcję.

Walidacja podpisów webhooków (v3), aby nigdy nie ufać sfałszowanemu ładunkowi

Waliduj każdy przychodzący webhook za pomocą podpisu v3. HubSpot podpisuje każde żądanie sekretem Twojej aplikacji i wysyła dwa nagłówki: X-HubSpot-Signature-v3 oraz X-HubSpot-Request-Timestamp. Odrzuć wszystko, co jest starsze niż 5 minut, odbuduj ciąg źródłowy jako metoda + pełny URL + surowe ciało żądania + znacznik czasu, zastosuj HMAC-SHA256 z sekretem aplikacji, zakoduj wynik w base64 i porównaj w stałym czasie.

Jeśli to pominiesz, każdy, kto odgadnie URL Twojego webhooka, może sfałszować aktualizację oferty. Walidacja nie jest opcjonalna. Dokumentacja walidacji żądań HubSpota oraz changelog podpisów v3 precyzują dokładny przepis. Oto on jako middleware gotowy do wdrożenia w Express:

import crypto from "crypto";

const CLIENT_SECRET = process.env.HUBSPOT_APP_SECRET; // from your private app settings
const MAX_AGE_MS = 5 * 60 * 1000; // reject anything older than 5 minutes

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

  // 1. Reject stale requests (replay protection)
  if (!signature || !timestamp || Date.now() - Number(timestamp) > MAX_AGE_MS) {
    return res.sendStatus(401);
  }

  // 2. Rebuild the exact source string: method + full URL + raw body + timestamp
  const uri = `https://${req.get("host")}${req.originalUrl}`;
  const source = `${req.method}${uri}${req.rawBody}${timestamp}`;

  // 3. HMAC-SHA256 with the app secret, base64-encoded
  const hash = crypto
    .createHmac("sha256", CLIENT_SECRET)
    .update(source, "utf8")
    .digest("base64");

  // 4. Constant-time compare against the header
  const expected = Buffer.from(hash);
  const received = Buffer.from(signature);
  if (expected.length !== received.length ||
      !crypto.timingSafeEqual(expected, received)) {
    return res.sendStatus(401);
  }
  next();
}

Ta sama kontrola jako funkcja w Pythonie, aby objąć oba stosy technologiczne:

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 minutes

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

    # 2. method + full 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. Constant-time compare
    return hmac.compare_digest(expected, signature)

Pułapka, która kosztuje ludzi całe popołudnia: HubSpot podpisuje pełny docelowy URL, czyli schemat, host i ścieżkę razem. Za proxy, balanserem obciążenia lub tunelem ngrok, req.get("host") może raportować wewnętrzny host zamiast publicznego, który podpisał HubSpot. Jeśli walidacja ciągle zawodzi przy ładunku, co do którego jesteś pewien, że jest legitny, zaloguj dokładny URI, który odbudowałeś, i porównaj go znak po znaku z publicznym URL webhooka.

Limity szybkości, błędy 429 i Batch API: Co uruchomiliśmy na produkcji

Prywatne aplikacje otrzymują około 10 żądań na sekundę (100 na 10 sekund w planach Free/Starter, 190 na 10 sekund w Pro/Enterprise) z dziennym limitem między 250 000 a 1 000 000. Pułapka: CRM Search ma osobny limit 4 żądań na sekundę, a endpointy wsadowe (batch) przyjmują maksymalnie 100 rekordów na żądanie. Wytyczne dotyczące użytkowania HubSpota wymieniają poziomy.

Oto miejsce, gdzie teoria zderzyła się z czerwoną tablicą kontrolną na stagingu. Podczas uzupełniania danych tej wiosny wypchnęliśmy około 8000 istniejących rekordów do HubSpota z wewnętrznego narzędzia do zgłoszeń i wzbogaciliśmy każdy z nich wyszukiwaniem w CRM Search. Uruchamialiśmy @hubspot/api-client v14 po stronie Node i hubspot-api-client v12 dla worker'a enrichingu w Pythonie. Masowe zapisy przebiegły dobrze. Wywołania Search padły w ciągu minuty, ponieważ nasz worker odpalał Search z prędkością około 15 req/s wobec twardego sufity 4 req/s, którego nie uwzględniliśmy osobno.

Dwie zmiany to naprawiły. Po pierwsze, wrapper retry, który odczytuje nagłówki odpowiedzi X-HubSpot-RateLimit-* i stosuje wycofywanie się (backoff) przy błędzie 429:

// Wrap any HubSpot call; retries on 429 with exponential backoff
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;

      // Honor HubSpot's reset window if the header is present
      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++;
    }
  }
}

Po drugie, przestaliśmy zapisywać rekordy pojedynczo. Endpoint batch przyjmuje do 100 rekordów na POST /crm/v3/objects/{objectType}/batch/create, więc podzieliliśmy uzupełnianie danych na 80 wywołań wsadowych zamiast 8000 pojedynczych POSTów:

// HubSpot batch endpoints accept at most 100 records per request
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, chunked to 100 at a time
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`);
  }
}

Ograniczenie workera Search do 4 req/s i wsadowe zapisy zamieniły proces tonący w retryach w taki, który zakończył się spokojnie. Jeśli masz zapamiętać jedną liczbę z tej sekcji, niech to będzie 4: limit CRM Search to granica, która boli na produkcji, i o której każdy przegląd zapomina wspomnieć. Stary limit batch „10 dla kontaktów” zresztą już nie istnieje; obecny to 100 dla wszystkich typów obiektów.

Kierunek dwukierunkowy: Zapisywanie zmian z powrotem do HubSpot bez nieskończonych pętli

Synchronizacja dwukierunkowa zapisuje zmiany z powrotem do HubSpota z Twojego narzędzia wewnętrznego, a także je odczytuje. Niebezpieczeństwem jest pętla sprzężenia zwrotnego: Twój zapis z powrotem wyzwala dokładnie ten webhook, który uruchomił Twój handler, który znowu zapisuje, i tak w kółko. Zapobiegaj temu za pomocą klucza idempotentności (pomijaj zmiany, które już zastosowałeś) i flagi źródła (ignoruj przychodzące zdarzenia spowodowane przez Twoje własne narzędzie).

const processed = new Set(); // use Redis or a unique DB constraint in production

async function writeBackToHubSpot(record) {
  // Dedup key: object id + a hash of the change we're about to apply
  const key = `${record.id}:${record.updatedHash}`;
  if (processed.has(key)) return; // already synced this exact change
  processed.add(key);

  await withRetry(() =>
    hubspot.crm.contacts.basicApi.update(record.id, {
      // Tag the source so the resulting webhook is ignored by our own receiver
      // (check for source: "internal-tool" before acting on an inbound event)
      properties: { internal_status: record.status, last_sync_source: "internal-tool" },
    })
  );
}

Wzorzec jest prosty, ale jego pominięcie powoduje, że synchronizacja cicho podwaja wolumen zapisów w ciągu nocy. Gdy dane są czyste w obu kierunkach, zespoły często przekazują je dalej do pipeline'u AI SDR lub warstwy raportowania. Poradnik integracji z HubSpot firmy Nango to solidne odniesienie tylko dla Node, jeśli chcesz drugiego spojrzenia na synchronizację dwukierunkową, choć będziesz musiał samodzielnie przenieść ideę zapobiegania pętlom.

Czy budować to wewnętrznie, czy zatrudnić partnera integracyjnego?

Buduj wewnętrznie, gdy synchronizacja jest mała, stabilna i posiadająca właściciela: przepływ jednokierunkowy, kilka obiektów i inżynier, który może absorbować zmiany łamiące kompatybilność wprowadzane przez HubSpot mniej więcej dwa razy w roku. Zatrudnij partnera, gdy potrzebujesz synchronizacji dwukierunkowej, modelowania obiektów niestandardowych lub gdy nikt w zespole nie może wziąć odpowiedzialności za bieżącą konserwację. Decydującym czynnikiem rzadko jest początkowa budowa; chodzi o to, kto będzie tego pilnował za rok.

Oto uczciwa lista kontrolna. Zbuduj to sam, jeśli: kierunek jest jednokierunkowy, synchronizujesz standardowe obiekty, masz developera, który może hostować endpoint webhooka, i ktoś zauważy, gdy ładunki zaczną zawodzić. Wszystko powyżej jest Twoim planem.

Zatrudnij partnera, jeśli: potrzebujesz synchronizacji dwukierunkowej z zapobieganiem pętlom dla kilku obiektów, modelujesz obiekty niestandardowe z typed associations, łączysz wiele systemów (HubSpot plus ERP plus billing) lub osoba, która miałaby to utrzymywać, jest już przeciążona. HubSpot używa wersjonowania API opartego na datach ze zmianami łamiącymi kompatybilność tylko około dwa razy w roku, co brzmi łagodnie, dopóki jedna z nich nie spadnie w najbardziej zajęty tydzień, a nie ma właściciela. To ogon konserwacji, a nie pierwszy deploy, jest tym, co cicho pogrąża wewnętrzne integracje. Jeśli wolisz tego nie posiadać, tutaj wchodzą nasze usługi niestandardowej integracji CRM.

Kluczowe wnioski

• Nie ma już klucza API HubSpot. Używaj tokena dostępu prywatnej aplikacji dla jednokontowego narzędzia wewnętrznego; OAuth jest tylko dla publicznych, wielokontowych aplikacji.
• Zawsze waliduj X-HubSpot-Signature-v3 przed zaufaniem ładunkowi webhooka. Odbuduj ciąg źródłowy z pełnym docelowym URL.
• Szanuj limit 4 req/s dla CRM Search i dziel duże zapisy na partie po 100 z mechanizmem backoff przy błędzie 429.
• Preferuj webhooki nad odpytywaniem dla synchronizacji w czasie rzeczywistym, a integracja z HubSpot jest jednym z elementów szerszego stosu narzędzi AI dla biznesu.

Utknąłeś po stronie konserwacji lub chcesz drugiego spojrzenia przed wypuszczeniem produktu? Umów bezpłatną konsultację integracyjną. Bez presji; powyższy kod jest Twój do uruchomienia niezależnie od decyzji.

O autorze

Mert Batur Gurbuz jest współzałożycielem Techsy.io, gdzie zespół dostarcza agentów AI, systemy automatyzacji oraz pipeline'y voice/SDR dla klientów B2B. Studiuje na University of Birmingham i pisze o stosie narzędzi LLM, z którego zespół Techsy faktycznie korzysta w produkcji. Kredencje: Współzałożyciel, Techsy.io, University of Birmingham. Połącz się na LinkedIn.

Często zadawane pytania

Czy w 2026 roku nadal potrzebuję klucza API HubSpot?

Nie. HubSpot wycofał statyczne klucze API 30 listopada 2022 roku i nie są one już wspierane. Autouzupełnianie nadal sugeruje „hubspot api key” z przyzwyczajenia, ale nie ma czego pobierać. Dla jednokontowego narzędzia wewnętrznego utwórz prywatną aplikację w Ustawieniach i użyj jej tokena dostępu.

Jaka jest różnica między tokenem prywatnej aplikacji a OAuth dla HubSpot?

Token dostępu prywatnej aplikacji to statyczne poświadczenie dla jednego konta HubSpot, bez wygaśnięcia i bez procesu odświeżania, idealne dla narzędzia wewnętrznego. OAuth 2.0 jest dla publicznych, wielokontowych aplikacji, które inne firmy instalują w swoich własnych portalach; jego tokeny wygasają po około sześciu godzinach i wymagają cyklu odświeżania.

Jakie są limity szybkości API HubSpot w 2026 roku?

Prywatne aplikacje otrzymują około 10 żądań na sekundę (100 na 10 sekund w planach Free/Starter, 190 w Pro/Enterprise) z dziennym limitem od 250 000 do 1 000 000. API CRM Search ma osobny limit 4 żądań na sekundę, a endpointy batch przyjmują maksymalnie 100 rekordów na żądanie.

Jak zwalidować podpis webhooka HubSpot?

Użyj przepisu v3: odrzuć żądania, gdzie X-HubSpot-Request-Timestamp jest starszy niż pięć minut, a następnie zbuduj ciąg źródłowy złożony z metody, pełnego docelowego URL, surowego ciała żądania i znacznika czasu. Zastosuj HMAC-SHA256 z sekretem aplikacji, zakoduj wynik w base64 i porównaj go z X-HubSpot-Signature-v3 w stałym czasie.

Którego SDK HubSpot powinienem użyć, Node czy Python?

Oba są oficjalne i utrzymywane. Node używa @hubspot/api-client (v14), a Python hubspot-api-client (v12). Udostępniają ten sam model obiektów CRM v3, więc wybierz ten, który pasuje do Twojego stosu technologicznego. Ten przewodnik dostarcza identyczny kod autoryzacji i walidacji podpisu w obu językach.

Jak synchronizować HubSpot z niestandardowym narzędziem wewnętrznym w czasie rzeczywistym?

Zarejestruj subskrypcję webhooka w swojej prywatnej aplikacji dla obiektu i zdarzenia, które Cię interesują, a następnie hostuj endpoint HTTPS, na który HubSpot wysyła dane POST, gdy nastąpi pasująca zmiana. Zweryfikuj podpis, a następnie zapisz zmianę w swoim narzędziu wewnętrznym. Odpytuj tylko wtedy, gdy żadna subskrypcja webhooka nie obejmuje tego, czego potrzebujesz.

Czym jest Service Key HubSpot i czy powinienem go używać?

Service Key to poświadczenie na poziomie konta, tylko do danych, które HubSpot wprowadził do publicznej bety w lutym 2026 roku. Jest skierowane do zadań server-side, które operują tylko na danych. Dla standardowego narzędzia wewnętrznego dzisiaj token dostępu prywatnej aplikacji jest nadal bezpieczniejszym, lepiej udokumentowanym domyślnym wyborem; traktuj Service Keys jako beta, dopóki nie zostaną oficjalnie wydane.

Czy mogę przetestować integrację z HubSpot bez dotykania produkcji?

Tak. Utwórz piaskownicę developerską HubSpot i skieruj swój token prywatnej aplikacji na nią. Zakresy uprawnień, model obiektów, webhooki i limity szybkości zachowują się tak samo jak na produkcji, więc możesz tworzyć testowe kontakty i uruchamiać webhooki, nie zostawiając śmieciowych rekordów do posprzątania przez zespół sprzedaży.

Ile rekordów może przyjąć batch API HubSpot naraz?

Endpointy batch (POST /crm/v3/objects/{objectType}/batch/create i jego odpowiedniki do update i upsert) przyjmują maksymalnie 100 rekordów na żądanie. Dziel większe ładunki na grupy po 100. Starszy limit „10 rekordów dla kontaktów”, który niektóre poradniki nadal cytują, został usunięty; obecny to 100 dla wszystkich typów obiektów.

Czy powinienem budować to wewnętrznie, czy zatrudnić agencję?

Buduj wewnętrznie, gdy synchronizacja jest jednokierunkowa, używa standardowych obiektów i ma właściciela, który może absorbować zmiany łamiące kompatybilność wprowadzane przez HubSpot dwa razy w roku. Zatrudnij partnera do synchronizacji dwukierunkowej, modelowania obiektów niestandardowych lub gdy nikt nie może wziąć odpowiedzialności za konserwację. Pierwszy deploy jest łatwy; rok utrzymania po nim to prawdziwy koszt.