HubSpot API-Integration für individuelle interne Tools: Der Node- und Python-Guide (2026)

Suchen Sie noch nach einem HubSpot API-Key für Ihre HubSpot API-Integration? Sie können aufhören zu suchen: HubSpot hat statische API-Keys am 30. November 2022 abgeschafft, und das aktuelle Node-SDK (@hubspot/api-client, mittlerweile bei v14) akzeptiert ohnehin keinen mehr. Die richtige Zugangsart für ein internes Tool mit einem einzigen Account ist ein Private-App-Access-Token, und dieser Guide baut eine echte Synchronisation zwischen HubSpot und einem internen Tool auf, in Node und Python, vom ersten create contact-Aufruf bis zu einem signaturgeprüften Webhook.

Kurzantwort: Eine HubSpot API-Integration ermöglicht es einem individuellen internen Tool, CRM-Daten über die v3-REST-API von HubSpot zu lesen und zu schreiben. Für ein internes Tool mit einem einzigen Account authentifizieren Sie sich mit einem Private-App-Access-Token (HubSpot hat API-Keys 2022 abgeschafft) und synchronisieren Änderungen anschließend in Echtzeit über Webhooks statt über Polling.

Das bauen Sie in diesem Guide:

• Private-App-Token-Authentifizierung plus Ihren ersten create contact-Aufruf in Node und Python
• Einen Webhook-Receiver, der X-HubSpot-Signature-v3 validiert, bevor er einem Payload vertraut
• Eine 429-sichere Batch-100-Synchronisation in einen internen Ticket- oder ERP-Datensatz

Wie funktioniert eine HubSpot API-Integration für individuelle interne Tools?

Eine HubSpot API-Integration verbindet ein individuelles internes Tool (eine Ticketing-App, ein ERP-System, ein Billing-Dashboard, ein Kundenportal) über die v3-REST-API mit dem CRM von HubSpot. Ihr Tool liest und schreibt CRM-Objekte (Kontakte, Deals, Unternehmen oder benutzerdefinierte Objekte) über HTTPS mit einem Private-App-Access-Token, und Änderungen fließen in Echtzeit über Webhooks zurück.

Stellen Sie sich HubSpots CRM als Datenbank vor, mit der Sie über HTTP kommunizieren. Jeder Datensatz ist ein Objekt mit einem Typ und einer ID. Die HubSpot CRM API-Integration, die Sie hier bauen, erfüllt zwei Aufgaben: Sie schiebt Daten in HubSpot hinein (einen Kontakt anlegen, wenn ein Ticket geöffnet wird) und holt Daten wieder heraus (einen Deal lesen, wenn Ihr internes Dashboard rendert).

Eine Synchronisation läuft in eine von zwei Richtungen. Eine Ein-Wege-Synchronisation kopiert Änderungen von HubSpot in Ihr Tool oder von Ihrem Tool nach HubSpot. Eine Zwei-Wege-Synchronisation macht beides und braucht einen Schutz vor Endlosschleifen, den wir später behandeln. Und statt HubSpot jede Minute zu fragen, ob es etwas Neues gibt (Polling), registrieren Sie einen Webhook, damit HubSpot Sie sofort informiert, wenn sich ein Datensatz ändert.

Wenn Sie Ihre Daten lieber vollständig selbst besitzen möchten, statt überhaupt ein gehostetes CRM zu integrieren, ist das Selbst-Hosting eines Open-Source-CRM ein anderer Weg, den Sie vor Ihrer Entscheidung abwägen sollten. Wenn HubSpot aber bereits Ihre Source of Truth ist, läuft alles andere über die API.

Für ein internes Tool mit einem einzigen Account brauchen Sie kein OAuth und keinen Eintrag im App-Marketplace. Ein Private-App-Token und ein Webhook sind die gesamte Integration.

Authentifizierung 2026: Warum es keinen HubSpot API-Key mehr gibt

Für die HubSpot API-Authentifizierung bei einem internen Tool mit einem einzigen Account verwenden Sie einen Private-App-Access-Token. Das ist ein statischer Bearer-Token, den Sie einmal in Ihrem HubSpot-Account generieren, mit genau den Scopes, die Ihr Tool tatsächlich benötigt. Es gibt keinen Refresh-Flow und kein Ablaufdatum. OAuth existiert für öffentliche Multi-Account-Apps, nicht für das Dashboard, das Ihr Ops-Team intern betreibt.

Private-App-Token vs. der veraltete API-Key

Hier ist die Falle, in die die Hälfte der Entwickler tappt, die über diese Suche hier landen. HubSpot hat API-Keys am 30. November 2022 abgeschafft, und sie werden inzwischen überhaupt nicht mehr unterstützt. Die Autovervollständigung schlägt zwar noch "hubspot api key" vor, weil sich die Gewohnheit noch nicht geändert hat, aber es gibt keinen Key mehr zu holen. Greifen Sie stattdessen zu einer HubSpot Private App: Legen Sie sie in den Einstellungen an, gewähren Sie ihr die benötigten Scopes, und kopieren Sie den Access-Token aus dem Auth-Tab. HubSpots Übersicht zu Private Apps beschreibt die Einrichtung.

Zwei Regeln für den Token selbst. Vergeben Sie minimale Rechte: Wenn Ihr Tool nur Deals liest und Kontakte schreibt, fordern Sie crm.objects.contacts.write und crm.objects.deals.read an, nicht mehr. Und bewahren Sie den Token in einer Umgebungsvariable oder einem Secret-Manager auf, gesendet im Authorization: Bearer-Header, niemals hart codiert und niemals im Browser ausgeliefert.

Das Fazit ist einfach: Verwenden Sie für ein internes Tool einen Private-App-Access-Token. Greifen Sie nur dann zu OAuth, wenn daraus später eine öffentliche Multi-Account-App wird, die andere Unternehmen in ihre eigenen Portale installieren.

Ihr erster HubSpot API-Aufruf: Einen Kontakt in Node und Python anlegen

Der klassische erste Aufruf ist create contact, und die offiziellen SDKs erledigen das in wenigen Zeilen. Installieren Sie den Client, initialisieren Sie ihn mit Ihrem Private-App-Token aus der Umgebung, legen Sie dann einen Kontakt an und lesen Sie im Gegenzug einen Deal aus. Das ist genau das Muster, das Sie später für Unternehmen, Tickets und Aufrufe der HubSpot Custom Objects API wiederverwenden, nur der Objekttyp ändert sich.

Hier die Node-Version mit @hubspot/api-client (v14):

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

// Private-App-Token aus einem Secret-Manager oder einer Env-Var, niemals hart codiert
const hubspot = new Client({ accessToken: process.env.HUBSPOT_PRIVATE_APP_TOKEN });

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

// Deal anhand der ID auslesen
const deal = await hubspot.crm.deals.basicApi.getById(
  "1234567890",
  ["dealname", "amount", "dealstage"],
);
console.log(deal.properties.dealname, deal.properties.amount);

Und dasselbe in Python mit 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 aus der Umgebung, nicht aus der Versionskontrolle
client = HubSpot(access_token=os.environ["HUBSPOT_PRIVATE_APP_TOKEN"])

# Kontakt anlegen
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)

# Deal anhand der ID auslesen
deal = client.crm.deals.basic_api.get_by_id(
    deal_id="1234567890",
    properties=["dealname", "amount", "dealstage"],
)
print(deal.properties["dealname"], deal.properties["amount"])

Profi-Tipp: Testen Sie zuerst gegen eine HubSpot Developer Sandbox, niemals direkt in der Produktivumgebung. Ein fehlerhafter Create-Aufruf in Produktion hinterlässt echten Datenmüll, den Ihr Sales-Team aufräumen muss. Token, Scopes und Objektmodell verhalten sich in der Sandbox identisch.

Wie synchronisieren Sie HubSpot in Echtzeit mit einem internen Tool?

Verwenden Sie Webhooks, nicht Polling. Registrieren Sie in Ihrer Private App ein Webhook-Abonnement für das Objekt und Ereignis, das Sie interessiert (etwa deal.propertyChange), richten Sie es auf einen von Ihnen gehosteten HTTPS-Endpunkt, und HubSpot sendet Ihnen per POST ein kleines JSON-Array, sobald eine passende Änderung eintritt. Pollen Sie nur, wenn für das, was Sie beobachten müssen, kein Abonnement existiert.

Der Gewinn ist Effizienz. Polling fragt jede Minute "gibt es etwas Neues?" und verbraucht dabei Ihr Rate-Limit; ein Webhook meldet sich genau in dem Moment, in dem sich ein Deal ändert. Dieser Unterschied macht sich bei Skalierung bemerkbar, und Webhooks sind heute Standard, nicht exotisch: Postmans State of the API Report 2025, eine Umfrage unter mehr als 5.700 Entwicklern, fand heraus, dass sich rund die Hälfte der Teams darauf verlässt.

Registrieren Sie das Abonnement im Webhooks-Tab Ihrer Private App, legen Sie die Ziel-URL fest und wählen Sie die Events aus. HubSpot sendet ein Array von Event-Objekten, jedes mit subscriptionType, objectId und der Angabe, was sich geändert hat. Hier ein Receiver-Stub in Node mit Express:

import express from "express";

const app = express();
// Rohdaten erfassen: Sie brauchen die exakten Bytes, um die Signatur im nächsten Schritt zu validieren
app.use(express.json({
  verify: (req, _res, buf) => { req.rawBody = buf.toString("utf8"); },
}));

// HubSpot sendet per POST ein Array von Events an diese 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);
    // Vertrauen Sie diesem Payload noch nicht. Der nächste Abschnitt validiert ihn, bevor wir etwas damit tun.
  }
  res.sendStatus(200);
});

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

Hier wird der Build-along konkret. Nehmen wir an, Sie synchronisieren einen Deal in den ERP-Datensatz eines kleinen Fertigungsbetriebs: Der Webhook feuert, Ihr Handler legt das passende ERP-Ticket an oder aktualisiert es, und Ihr Ops-Team sieht die Änderung, ohne HubSpot anzufassen. Es ist derselbe Echtzeit-Ansatz, den wir verwenden, um einen Voice-Agent mit einem CRM zu synchronisieren; nur der Auslöser ist hier eine Eigenschaftsänderung statt eines Telefonanrufs. Eine Warnung: Der Stub oben vertraut allem, was per POST an ihn geschickt wird. Beheben Sie das, bevor Sie live gehen.

Webhook-Signaturen (v3) validieren, damit Sie nie einem gefälschten Payload vertrauen

Validieren Sie jeden eingehenden Webhook mit der v3-Signatur. HubSpot signiert jede Anfrage mit Ihrem App-Secret und sendet zwei Header, X-HubSpot-Signature-v3 und X-HubSpot-Request-Timestamp. Lehnen Sie alles ab, was älter als 5 Minuten ist, bauen Sie den Quellstring als Methode + vollständige URL + Rohdaten + Timestamp neu zusammen, wenden Sie HMAC-SHA256 mit dem App-Secret darauf an, kodieren Sie ihn base64 und vergleichen Sie ihn in konstanter Zeit.

Wenn Sie das überspringen, kann jeder, der Ihre Webhook-URL errät, ein Deal-Update fälschen. Validierung ist nicht optional. HubSpots Dokumentation zur Validierung von Anfragen und das v3-Signaturen-Changelog beschreiben das genaue Rezept. Hier als fertige Express-Middleware:

import crypto from "crypto";

const CLIENT_SECRET = process.env.HUBSPOT_APP_SECRET; // aus Ihren Private-App-Einstellungen
const MAX_AGE_MS = 5 * 60 * 1000; // alles ablehnen, was älter als 5 Minuten ist

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

  // 1. Veraltete Anfragen ablehnen (Replay-Schutz)
  if (!signature || !timestamp || Date.now() - Number(timestamp) > MAX_AGE_MS) {
    return res.sendStatus(401);
  }

  // 2. Den exakten Quellstring neu zusammenbauen: Methode + vollständige URL + Rohdaten + Timestamp
  const uri = `https://${req.get("host")}${req.originalUrl}`;
  const source = `${req.method}${uri}${req.rawBody}${timestamp}`;

  // 3. HMAC-SHA256 mit dem App-Secret, base64-kodiert
  const hash = crypto
    .createHmac("sha256", CLIENT_SECRET)
    .update(source, "utf8")
    .digest("base64");

  // 4. Vergleich in konstanter Zeit mit dem 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();
}

Derselbe Check als Python-Funktion, damit beide Stacks abgedeckt sind:

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 Minuten

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

    # 2. Methode + vollständige URL + Rohdaten + 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. Vergleich in konstanter Zeit
    return hmac.compare_digest(expected, signature)

Die Falle, die Leute einen ganzen Nachmittag kostet: HubSpot signiert die vollständige Ziel-URL, Schema, Host und Pfad zusammen. Hinter einem Proxy, einem Load Balancer oder einem ngrok-Tunnel kann req.get("host") den internen Host statt des öffentlichen melden, den HubSpot signiert hat. Wenn die Validierung bei einem Payload, den Sie für legitim halten, immer wieder fehlschlägt, loggen Sie die exakte URI, die Sie zusammengebaut haben, und vergleichen Sie sie Zeichen für Zeichen mit Ihrer öffentlichen Webhook-URL.

Rate-Limits, 429er und die Batch-API: Was wir in Produktion gefahren haben

Private Apps bekommen etwa 10 Requests pro Sekunde (100 pro 10 Sekunden bei Free/Starter, 190 pro 10 Sekunden bei Pro/Enterprise) mit einem Tages-Limit zwischen 250.000 und 1.000.000. Die Falle: CRM Search ist separat auf 4 Requests pro Sekunde begrenzt, und Batch-Endpunkte akzeptieren maximal 100 Datensätze pro Request. HubSpots Nutzungsrichtlinien listen die Stufen auf.

Hier traf die Theorie auf ein rotes Staging-Dashboard. Bei einem Backfill in diesem Frühjahr haben wir rund 8.000 bestehende Datensätze aus einem internen Ticketing-Tool in HubSpot geschoben und jeden davon mit einem CRM-Search-Lookup angereichert. Wir haben auf der Node-Seite @hubspot/api-client v14 und für einen Python-Enrichment-Worker hubspot-api-client v12 eingesetzt. Die Massen-Writes liefen problemlos. Die Search-Aufrufe brachen innerhalb einer Minute zusammen, weil unser Worker Search mit rund 15 Req/s gegen eine harte Grenze von 4 Req/s feuerte, die wir nicht separat eingeplant hatten.

Zwei Änderungen haben das Problem behoben. Erstens ein Retry-Wrapper, der die X-HubSpot-RateLimit-*-Response-Header ausliest und bei einem 429 zurückweicht:

// Umschließt jeden HubSpot-Aufruf; wiederholt bei 429 mit exponentiellem 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;

      // HubSpots Reset-Fenster respektieren, falls der Header vorhanden ist
      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++;
    }
  }
}

Zweitens haben wir aufgehört, Datensätze einzeln zu schreiben. Der Batch-Endpunkt nimmt bis zu 100 Datensätze pro POST /crm/v3/objects/{objectType}/batch/create entgegen, also haben wir den Backfill in 80 Batch-Aufrufe statt in 8.000 einzelne POSTs aufgeteilt:

// HubSpot-Batch-Endpunkte akzeptieren maximal 100 Datensätze pro 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, in Blöcken von je 100
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`);
  }
}

Den Search-Worker auf 4 Req/s zu drosseln und die Writes zu batchen, hat aus einem in Retries ertrinkenden Lauf einen gemacht, der ruhig durchlief. Wenn Sie sich eine Zahl aus diesem Abschnitt merken, dann diese: 4. Das CRM-Search-Limit ist die Grenze, die in Produktion tatsächlich zuschlägt, und genau die, die jeder Roundup-Artikel zu erwähnen vergisst. Die alte Batch-Grenze von "10 für Kontakte" gibt es übrigens nicht mehr; aktuell sind es 100, über alle Objekttypen hinweg.

Zwei-Wege-Synchronisation: Änderungen ohne Endlosschleifen an HubSpot zurückschreiben

Eine Zwei-Wege-Synchronisation schreibt Änderungen aus Ihrem internen Tool zurück nach HubSpot und liest sie zugleich ein. Die Gefahr ist eine Rückkopplungsschleife: Ihr Rückschreiben löst genau den Webhook aus, der Ihren Handler ausgelöst hat, der wieder schreibt, immer weiter. Verhindern Sie das mit einem Idempotenz-Schlüssel (bereits angewendete Änderungen überspringen) und einer Quell-Markierung (eingehende Events ignorieren, die Ihr eigenes Tool selbst verursacht hat).

const processed = new Set(); // in Produktion Redis oder einen eindeutigen DB-Constraint verwenden

async function writeBackToHubSpot(record) {
  // Dedup-Key: Objekt-ID + ein Hash der Änderung, die wir gleich anwenden
  const key = `${record.id}:${record.updatedHash}`;
  if (processed.has(key)) return; // diese exakte Änderung wurde bereits synchronisiert
  processed.add(key);

  await withRetry(() =>
    hubspot.crm.contacts.basicApi.update(record.id, {
      // Quelle markieren, damit der resultierende Webhook vom eigenen Receiver ignoriert wird
      // (vor dem Reagieren auf ein eingehendes Event auf source: "internal-tool" prüfen)
      properties: { internal_status: record.status, last_sync_source: "internal-tool" },
    })
  );
}

Das Muster ist klein, aber wer es überspringt, verdoppelt über Nacht unbemerkt sein Schreibvolumen. Sobald die Daten in beide Richtungen sauber sind, speisen Teams sie oft weiter in eine AI-SDR-Pipeline oder eine Reporting-Schicht ein. Nangos HubSpot-Integrations-Tutorial ist eine solide, reine Node-Referenz, wenn Sie eine zweite Perspektive auf Zwei-Wege-Synchronisation suchen; die Idee zum Verhindern von Schleifen müssen Sie sich allerdings selbst übertragen.

Sollten Sie das selbst bauen oder einen Integrationspartner beauftragen?

Bauen Sie selbst, wenn die Synchronisation klein, stabil und eindeutig verantwortet ist: ein Ein-Wege-Fluss, eine Handvoll Objekte und ein Entwickler, der die etwa zweimal im Jahr auftretenden Breaking Changes von HubSpot auffangen kann. Beauftragen Sie einen Partner, wenn Sie eine bidirektionale Synchronisation, die Modellierung benutzerdefinierter Objekte brauchen, oder wenn niemand im Team die laufende Wartung übernehmen kann. Entscheidend ist selten der erste Build, sondern wer in einem Jahr noch danach schaut.

Hier eine ehrliche Checkliste. Bauen Sie es selbst, wenn: die Richtung Ein-Wege ist, Sie Standardobjekte synchronisieren, Sie einen Entwickler haben, der einen Webhook-Endpunkt hosten kann, und jemand bemerkt, wenn ein Payload anfängt zu scheitern. Alles oben ist Ihr Bauplan.

Beauftragen Sie einen Partner, wenn: Sie eine Zwei-Wege-Synchronisation mit Schleifenschutz über mehrere Objekte brauchen, Sie benutzerdefinierte Objekte mit typisierten Verknüpfungen modellieren, Sie mehrere Systeme verdrahten (HubSpot plus ein ERP plus Billing), oder die Person, die es warten würde, bereits ausgelastet ist. HubSpot nutzt eine datumsbasierte API-Versionierung mit Breaking Changes nur etwa zweimal im Jahr, was harmlos klingt, bis einer davon genau in Ihrer arbeitsreichsten Woche landet und niemand zuständig ist. Nicht das erste Deployment, sondern dieser Wartungs-Rattenschwanz lässt interne Integrationen still und leise scheitern. Wenn Sie das lieber nicht selbst verantworten möchten, kommen genau hier unsere maßgeschneiderten CRM-Integrationsservices ins Spiel.

Die wichtigsten Erkenntnisse

• Es gibt keinen HubSpot API-Key mehr. Verwenden Sie für ein internes Tool mit einem einzigen Account einen Private-App-Access-Token; OAuth ist nur für öffentliche Multi-Account-Apps.
• Validieren Sie immer X-HubSpot-Signature-v3, bevor Sie einem Webhook-Payload vertrauen. Bauen Sie den Quellstring mit der vollständigen Ziel-URL neu zusammen.
• Beachten Sie das 4-Req/s-Limit für CRM Search und batchen Sie große Writes in Blöcken von 100 mit einem 429-Backoff.
• Bevorzugen Sie Webhooks gegenüber Polling für Echtzeit-Synchronisation; eine HubSpot-Integration ist nur ein Baustein eines umfassenderen KI-Tools für Unternehmen-Stacks.

Hängen Sie bei der Wartungsseite fest, oder wollen Sie vor dem Go-live noch eine zweite Meinung? Vereinbaren Sie eine kostenlose Integrationsberatung. Ganz ohne Druck: Der Code oben gehört ohnehin Ihnen, egal wofür Sie sich entscheiden.

Häufig gestellte Fragen

Brauche ich 2026 noch einen HubSpot API-Key?

Nein. HubSpot hat statische API-Keys am 30. November 2022 abgeschafft, und sie werden inzwischen überhaupt nicht mehr unterstützt. Die Autovervollständigung schlägt aus Gewohnheit noch "hubspot api key" vor, aber es gibt nichts mehr zu holen. Legen Sie für ein internes Tool mit einem einzigen Account stattdessen eine Private App in den Einstellungen an und verwenden Sie deren Access-Token.

Was ist der Unterschied zwischen einem Private-App-Token und OAuth bei HubSpot?

Ein Private-App-Access-Token ist ein statisches Credential für einen einzelnen HubSpot-Account, ohne Ablaufdatum und ohne Refresh-Flow, ideal für ein internes Tool. OAuth 2.0 ist für öffentliche Multi-Account-Apps gedacht, die andere Unternehmen in ihre eigenen Portale installieren; dessen Tokens laufen nach etwa sechs Stunden ab und erfordern einen Refresh-Zyklus.

Wie hoch sind HubSpots API-Rate-Limits im Jahr 2026?

Private Apps bekommen etwa 10 Requests pro Sekunde (100 pro 10 Sekunden bei Free/Starter, 190 bei Pro/Enterprise) mit einem Tages-Limit von 250.000 bis 1.000.000. Die CRM-Search-API ist separat auf 4 Requests pro Sekunde begrenzt, und Batch-Endpunkte akzeptieren maximal 100 Datensätze pro Request.

Wie validiere ich eine HubSpot-Webhook-Signatur?

Verwenden Sie das v3-Rezept: Lehnen Sie Anfragen ab, bei denen X-HubSpot-Request-Timestamp älter als fünf Minuten ist, und bauen Sie dann einen Quellstring aus Methode plus vollständiger Ziel-URL plus Rohdaten plus Timestamp zusammen. Wenden Sie HMAC-SHA256 mit Ihrem App-Secret darauf an, kodieren Sie das Ergebnis base64 und vergleichen Sie es in konstanter Zeit mit X-HubSpot-Signature-v3.

Welches HubSpot-SDK sollte ich verwenden, Node oder Python?

Beide sind offiziell und werden gepflegt. Node nutzt @hubspot/api-client (v14), Python nutzt hubspot-api-client (v12). Beide stellen dasselbe v3-CRM-Objektmodell bereit, wählen Sie also einfach das, was zu Ihrem Stack passt. Dieser Guide liefert identischen Auth- und Signaturvalidierungs-Code in beiden Sprachen.

Wie synchronisiere ich HubSpot in Echtzeit mit einem individuellen internen Tool?

Registrieren Sie in Ihrer Private App ein Webhook-Abonnement für das Objekt und Ereignis, das Sie interessiert, und hosten Sie dann einen HTTPS-Endpunkt, an den HubSpot per POST sendet, sobald eine passende Änderung eintritt. Validieren Sie die Signatur und schreiben Sie die Änderung anschließend in Ihr internes Tool. Pollen Sie nur, wenn kein Webhook-Abonnement das abdeckt, was Sie brauchen.

Was ist ein HubSpot Service Key, und sollte ich ihn verwenden?

Ein Service Key ist ein account-weites, reines Daten-Credential, das HubSpot im Februar 2026 in die Public Beta gebracht hat. Er ist auf serverseitige Jobs ausgerichtet, die ausschließlich mit Daten arbeiten. Für ein Standard-internes-Tool ist heute ein Private-App-Access-Token noch immer die sicherere, besser dokumentierte Standardwahl; behandeln Sie Service Keys bis zu ihrem Beta-Ende als solche.

Kann ich eine HubSpot-Integration testen, ohne die Produktivumgebung anzufassen?

Ja. Legen Sie eine HubSpot Developer Sandbox an und richten Sie Ihren Private-App-Token darauf aus. Scopes, Objektmodell, Webhooks und Rate-Limits verhalten sich genauso wie in Produktion, sodass Sie Test-Kontakte anlegen und Webhooks auslösen können, ohne Ihrem Sales-Team später Datenmüll zum Aufräumen zu hinterlassen.

Wie viele Datensätze kann die HubSpot-Batch-API auf einmal verarbeiten?

Die Batch-Endpunkte (POST /crm/v3/objects/{objectType}/batch/create und die entsprechenden Update- und Upsert-Varianten) akzeptieren maximal 100 Datensätze pro Request. Teilen Sie größere Payloads in Gruppen von 100 auf. Die ältere Grenze von "10 Datensätzen für Kontakte", die manche Tutorials noch zitieren, wurde entfernt; aktuell sind es 100, über alle Objekttypen hinweg.

Sollte ich das selbst bauen oder eine Agentur beauftragen?

Bauen Sie selbst, wenn die Synchronisation Ein-Wege ist, Standardobjekte nutzt und einen Verantwortlichen hat, der HubSpots zweimal jährliche Breaking Changes auffangen kann. Beauftragen Sie einen Partner für bidirektionale Synchronisation, die Modellierung benutzerdefinierter Objekte, oder wenn niemand die Wartung übernehmen kann. Das erste Deployment ist einfach. Das Jahr an laufender Pflege danach ist der eigentliche Kostenpunkt.