HubSpot API-integration til interne værktøjer: En Node + Python-guide (2026)

HubSpot API-integration til interne værktøjer: En Node + Python-guide (2026)

Leder du stadig efter en HubSpot API-nøgle for at sætte din HubSpot API-integration op? Stop med at lede. HubSpot udfasede statiske API-nøgler den 30. november 2022, og det nuværende Node SDK (@hubspot/api-client, nu version 14) accepterer alligevel ikke en sådan. Den rigtige legitimationsnøgle til et internt værktøj til én konto er et access token fra en privat app, og denne guide viser, hvordan du bygger en reel synkronisering fra HubSpot til et internt værktøj i både Node og Python – fra dit første create contact-kald til en signaturvalideret webhook.

Kort svar: En HubSpot API-integration lader et custom internt værktøj læse og skrive CRM-data gennem HubSpots v3 REST API. Til et internt værktøj til én konto skal du autentificere med et access token fra en privat app (HubSpot udfasede API-nøgler i 2022) og derefter synkronisere ændringer i realtid med webhooks i stedet for polling.

Her er, hvad du kommer til at bygge:

• Autentificering med private app-tokens plus dit første create contact-kald i Node og Python
• En webhook-modtager, der validerer X-HubSpot-Signature-v3, før den stoler på en payload
• En 429-sikker batch-synkronisering af 100 poster ind i en intern billetsag- eller ERP-record

Hvordan fungerer HubSpot API-integration til interne værktøjer?

En HubSpot API-integration forbinder et custom internt værktøj (en billetapp, et ERP-system, et faktureringsdashboard eller en kundeportal) med HubSpots CRM via dets v3 REST API. Dit værktøj læser og skriver CRM-objekter (kontakter, deals, virksomheder eller brugerdefinerede objekter) over HTTPS med et access token fra en privat app, og ændringer i realtid strømmer tilbage gennem webhooks.

Tænk på HubSpots CRM som en database, du taler med over HTTP. Hver post er et objekt med en type og et ID. Den hubspot crm api integration, du bygger, har to opgaver: den pusher data ind i HubSpot (opret en kontakt, når en sag åbnes) og trækker data ud af det (læs et deal, når dit interne dashboard renderes).

Synkroniseringen kører i en af to retninger. En vejs-synkronisering kopierer ændringer fra HubSpot til dit værktøj eller fra dit værktøj til HubSpot. En to-vejs-synkronisering gør begge dele og kræver løkkebeskyttelse, hvilket vi dækker senere. Og i stedet for at spørge HubSpot "er der noget nyt?" hvert minut (polling), registrerer du en webhook, så HubSpot fortæller dig det øjeblik, en post ændres.

Hvis du hellere vil eje dine data fuldt ud frem for at integrere en hosted CRM-løsning overhovedet, er selvhosting af en open-source CRM en anden vej, det er værd at overveje, før du binder dig. Men hvis HubSpot allerede er din sandhedskilde, er API'en måden, alt andet kommunikerer med den på.

Til et internt værktøj til én konto behøver du ikke OAuth eller en listing i app-markedspladsen. Et token fra en privat app og en webhook er hele integrationen.

Autentificering i 2026: Hvorfor der ikke længere findes en HubSpot API-nøgle

Til HubSpot API-autentificering på et internt værktøj til én konto skal du bruge et access token fra en privat app. Det er et statisk bearer-token, du genererer én gang i din HubSpot-konto, scoped til præcis de objekter, dit værktøj rører ved. Der er ingen refresh-flow og ingen udløb. OAuth eksisterer til offentlige apps med flere konti, ikke til det dashboard, dit ops-team kører internt.

Private App Token vs. den udfasede API-nøgle

Her er faldgruben, der får halvdelen af de udviklere, der lander på denne SERP, til at snuble. HubSpot udfasede API-nøgler den 30. november 2022, og de er fuldt ud usupporterede nu. Autocomplete foreslår stadig "hubspot api key", fordi muskelhukommelsen ikke har hentet ind, men der er ingen nøgle at hente. Grib i stedet efter en hubspot private app: opret den i Indstillinger, tildel de scopes, den har brug for, og kopier access tokenet fra fanen Auth. HubSpots oversigt over private apps dækker opsætningen.

To regler for selve tokenet. Tildel mindste privilegium: hvis dit værktøj kun læser deals og skriver kontakter, skal du anmode om crm.objects.contacts.write og crm.objects.deals.read, intet mere. Og gem tokenet i en miljøvariabel eller en secret manager, sendt i Authorization: Bearer-headeren, aldrig hardcodet og aldrig sendt til browseren.

Konklusionen er simpel. Til et internt værktøj skal du bruge et access token fra en privat app. Grib kun efter OAuth, hvis dette senere bliver en offentlig app med flere konti, som andre virksomheder installerer i deres egne portaler.

Dit første HubSpot API-kald: Opret en kontakt i Node og Python

Det kanoniske første kald er create contact, og de officielle SDK'er gør det til få linjer. Installer klienten, initialiser den med dit private app-token fra miljøet, opret derefter en kontakt og læs et deal tilbage. Dette er samme mønster, du vil genbruge til virksomheder, sager og hubspot custom objects api-kald; kun objekttypen ændres.

Her er Node-versionen med @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);

Og det samme i Python med 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"])

Pro-tip: Test mod en HubSpot developer sandbox, aldrig produktion først. Et mislykket create-kald i produktionen efterlader rigtige junk-records, som dit salgstteam skal rydde op i. Tokenet, scopesene og objektmodellen opfører sig identisk i sandboxen.

Hvordan synkroniserer du HubSpot til et internt værktøj i realtid?

Brug webhooks, ikke polling. Registrer et webhook-abonnement i din private app for det objekt og den begivenhed, du er interesseret i (f.eks. deal.propertyChange), peg det mod et HTTPS-endpoint, du hoster, og HubSpot POSTER en lille JSON-array til dig i det øjeblik, en matchende ændring sker. Brug kun polling, når der ikke findes et abonnement for det, du skal overvåge.

Gevinsten er effektivitet. Polling spørger "er der noget nyt?" hvert minut og brænder din rate limit af ved at gøre det; en webhook fortæller dig bare i det øjeblik, et deal ændres. Den forskel betyder noget i stor skala, og webhooks er mainstream nu, ikke eksotiske: Postmans State of the API Report 2025, en undersøgelse af mere end 5.700 udviklere, fandt, at omkring halvdelen af teamsene stolede på dem.

Registrer abonnementet under din private apps Webhooks-fane, indstil mål-URL'en, og vælg begivenhederne. HubSpot sender en array af event-objekter, der hver bærer subscriptionType, objectId og hvad der ændrede sig. Her er en receiver-stub i Node med 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"));

Her bliver build-alongen rigtig. Lad os sige, at du synkroniserer et deal ind i en lille producents ERP-record: webhook'en fyres, din handler opretter eller opdaterer den matchende ERP-billet, og dit ops-team ser ændringen uden at røre HubSpot. Det er samme realtidsmetode, vi bruger til at synkronisere en voice agent til en CRM, kun er triggeren en egenskabsændring i stedet for et telefonopkald. En advarsel: stubben ovenfor stoler på alt, der POSTES til den. Ret det, før du går live.

Validering af webhook-signaturer (v3), så du aldrig stoler på en forfalsket payload

Valider hver indgående webhook med v3-signaturen. HubSpot signerer hver anmodning med din app-secret og sender to headers, X-HubSpot-Signature-v3 og X-HubSpot-Request-Timestamp. Afvis alt, der er ældre end 5 minutter, genopbyg kildestrengen som method + fuld URL + raw body + timestamp, HMAC-SHA256 den med app-secret'en, base64-enkod, og sammenlign i konstant tid.

Hvis du springer dette over, kan alle, der gætter din webhook-URL, forfalske en deal-opdatering. Validering er ikke valgfri. HubSpots dokumentation om validering af anmodninger og changelogen for v3-signaturer specificerer den nøjagtige opskrift. Her er det som drop-in Express middleware:

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

Den samme check som en Python-funktion, så begge stacks er dækket:

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)

Faldgruben, der koster folk en eftermiddag: HubSpot signerer den fulde mål-URL, scheme, host og path samlet. Bag en proxy, en load balancer eller en ngrok-tunnel kan req.get("host") rapportere den interne host i stedet for den offentlige, som HubSpot signede. Hvis valideringen fortsat fejler på en payload, du er sikker på er legitim, så log den nøjagtige URI, du genopbyggede, og sammenlign den med din offentlige webhook-URL, tegn for tegn.

Rate limits, 429'er og Batch API: Hvad vi kørte i produktion

Private apps får cirka 10 anmodninger per sekund (100 per 10 sekunder på Free/Starter, 190 per 10 sekunder på Pro/Enterprise) med et dagligt loft mellem 250.000 og 1.000.000. Fælden: CRM Search er separat begrænset til 4 anmodninger per sekund, og batch-endpoints accepterer maksimalt 100 records per anmodning. HubSpots retningslinjer for brug lister niveauerne.

Her mødte teorien et rødt staging-dashboard. Under en backfill tidligere på foråret pushede vi cirka 8.000 eksisterende records ind i HubSpot fra et internt billetsagsværktøj og berigede hver enkelt med et CRM Search-opslag. Vi kørte @hubspot/api-client v14 på Node-siden og hubspot-api-client v12 til en Python-berigelsesworker. Bulk-skrivningerne gik fint. Search-kaldene krashede inden for et minut, fordi vores worker affyrede Search med omkring 15 req/s mod et hårdt loft på 4 req/s, som vi ikke havde budgetteret separat for.

To ændringer fik det til at virke. For det første en retry-wrapper, der læser X-HubSpot-RateLimit-* response-headers og bakker ud ved en 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++;
    }
  }
}

For det andet holdt vi op med at skrive records én ad gangen. Batch-endpointet tager op til 100 records per POST /crm/v3/objects/{objectType}/batch/create, så vi chunkede backfillen i 80 batch-kald i stedet for 8.000 enkelte POSTs:

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

At begrænse Search-worker'en til 4 req/s og batche skrivningerne gjorde en kørsel, der druknede i retries, til en, der blev færdig stille og roligt. Hvis du husker ét tal fra dette afsnit, så lad det være 4: CRM Search-loftet er den grænse, der bider i produktion, og det er den, hver roundup-post glemmer at nævne. Det gamle "10 for contacts"-batchloft er forresten væk; det aktuelle er 100 på tværs af objekttyper.

To-vejs: Skriv ændringer tilbage til HubSpot uden uendelige løkker

En to-vejs-synkronisering skriver ændringer tilbage til HubSpot fra dit interne værktøj samt læser dem ind. Faren er en feedback-løkke: din write-back trigger netop den webhook, der affyrede din handler, som skriver igen, for evigt. Forhindr det med en idempotensnøgle (spring ændringer over, du allerede har anvendt) og et source-flag (ignorer indgående events, dit eget værktøj har forårsaget).

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

Mønsteret er lille, men at springe det over er måden, hvorpå en synkronisering stille og roligt fordobler dit skrivevolumen natten over. Når dataene er rene i begge retninger, føder teams dem ofte downstream ind i en AI SDR-pipeline eller et rapporteringslag. Nangos HubSpot integration tutorial er en solid Node-only reference, hvis du vil have et andet bud på to-vejs-synkronisering, selvom du selv skal porte ideen om løkkeforebyggelse.

Skal du bygge dette in-house eller hyre en integrationspartner?

Byg in-house, når synkroniseringen er lille, stabil og ejet: et one-way flow, en håndfuld objekter og en ingeniør, der kan absorbere HubSpots cirka to årlige breaking changes. Hyr en partner, når du har brug for bidirektionel synkronisering, modellering af brugerdefinerede objekter, eller når ingen på teamet kan eje den løbende vedligeholdelse. Den afgørende faktor er sjældent det indledende build; det er, hvem der holder øje med det om et år.

Her er en ærlig tjekliste. Byg det selv, hvis: retningen er one-way, du synkroniserer standardobjekter, du har en udvikler, der kan hoste et webhook-endpoint, og nogen vil bemærke, når en payload begynder at fejle. Alt ovenfor er din blueprint.

Hyr en partner, hvis: du har brug for to-vejs-synkronisering med løkkeforebyggelse på tværs af flere objekter, du modellerer brugerdefinerede objekter med typed associations, du kobler flere systemer sammen (HubSpot plus et ERP plus fakturering), eller personen, der ville vedligeholde det, allerede er ved kapacitetsgrænsen. HubSpot bruger datobaseret API-versionering med breaking changes kun cirka to gange om året, hvilket lyder mildt, indtil en rammer i din travleste uge, og der ikke er nogen ejer. Den vedligeholdelseshale, ikke den første deploy, er det, der stille og roligt sænker interne integrationer. Hvis du hellere vil undgå at eje det, er det her, vores custom CRM-integrationstjenester kommer ind i billedet.

Vigtigste pointer

• Der findes ikke længere nogen HubSpot API-nøgle. Brug et access token fra en privat app til et internt værktøj til én konto; OAuth er kun til offentlige apps med flere konti.
• Valider altid X-HubSpot-Signature-v3, før du stoler på en webhook-payload. Genopbyg kildestrengen med den fulde mål-URL.
• Respekter 4 req/s CRM Search-loftet og batch store writes i klumper af 100 med en 429-backoff.
• Foretræk webhooks frem for polling til realtidssynkronisering, og en HubSpot-integration er én del af en bredere stack af AI-værktøjer til forretning.

Stuck på vedligeholdelsessiden, eller vil du have et ekstra par øjne, før du shipper? Book en gratis integrationskonsultation. Intet pres hverken den ene eller anden vej; koden ovenfor er din at køre uanset hvad.

Ofte stillede spørgsmål

Har jeg stadig brug for en HubSpot API-nøgle i 2026?

Nej. HubSpot udfasede statiske API-nøgler den 30. november 2022, og de er fuldt ud usupporterede. Autocomplete foreslår stadig "hubspot api key" af vane, men der er intet at hente. Til et internt værktøj til én konto skal du oprette en privat app i Indstillinger og bruge dens access token i stedet.

Hvad er forskellen mellem et private app-token og OAuth til HubSpot?

Et access token fra en privat app er en statisk legitimationsnøgle til en enkelt HubSpot-konto uden udløb og uden refresh-flow, ideel til et internt værktøj. OAuth 2.0 er til offentlige apps med flere konti, som andre virksomheder installerer i deres egne portaler; dets tokens udløber på cirka seks timer og kræver en refresh-cyklus.

Hvad er HubSpots API-rate limits i 2026?

Private apps får cirka 10 anmodninger per sekund (100 per 10 sekunder på Free/Starter, 190 på Pro/Enterprise) med et dagligt loft på 250.000 til 1.000.000. CRM Search API'en er separat begrænset til 4 anmodninger per sekund, og batch-endpoints accepterer maksimalt 100 records per anmodning.

Hvordan validerer jeg en HubSpot webhook-signatur?

Brug v3-opskriften: afvis anmodninger, hvor X-HubSpot-Request-Timestamp er ældre end fem minutter, og byg derefter en kildestreng af method plus fuld mål-URL plus raw body plus timestamp. HMAC-SHA256 den med din app-secret, base64-enkod resultatet, og sammenlign det med X-HubSpot-Signature-v3 i konstant tid.

Hvilket HubSpot SDK skal jeg bruge, Node eller Python?

Begge er officielle og vedligeholdes. Node bruger @hubspot/api-client (v14) og Python bruger hubspot-api-client (v12). De eksponerer samme v3 CRM-objektmodel, så vælg den, der matcher din stack. Denne guide leverer identisk auth- og signaturvalideringskode på begge sprog.

Hvordan synkroniserer jeg HubSpot med et custom internt værktøj i realtid?

Registrer et webhook-abonnement i din private app for det objekt og den begivenhed, du er interesseret i, og host derefter et HTTPS-endpoint, som HubSpot POSTER til, når en matchende ændring sker. Valider signaturen, og skriv derefter ændringen ind i dit interne værktøj. Brug kun polling, når intet webhook-abonnement dækker det, du har brug for.

Hvad er en HubSpot Service Key, og skal jeg bruge den?

En Service Key er en konto-niveau, data-only legitimationsnøgle, som HubSpot lancerede i offentlig beta i februar 2026. Den er rettet mod server-side jobs, der kun rører ved data. Til et standard internt værktøj i dag er et access token fra en privat app stadig den sikrere, bedre dokumenterede standard; behandl Service Keys som beta, indtil de graduerer.

Kan jeg teste en HubSpot-integration uden at røre produktion?

Ja. Opret en HubSpot developer sandbox, og peg dit private app-token mod den. Scopes, objektmodel, webhooks og rate limits opfører sig ligesom i produktion, så du kan oprette testkontakter og affyre webhooks uden at efterlade junk-records, som dit salgstteam skal rydde op i senere.

Hvor mange records kan HubSpot batch API tage ad gangen?

Batch-endpoints (POST /crm/v3/objects/{objectType}/batch/create og dets update- og upsert-søskende) accepterer maksimalt 100 records per anmodning. Chunk større payloads i grupper af 100. Det ældre "10 records for contacts"-loft, som nogle tutorials stadig citerer, er fjernet; 100 er aktuelt på tværs af objekttyper.

Skal jeg bygge dette in-house eller hyre et bureau?

Byg in-house, når synkroniseringen er one-way, bruger standardobjekter og har en ejer, der kan absorbere HubSpots to årlige breaking changes. Hyr en partner til bidirektionel synkronisering, modellering af brugerdefinerede objekter, eller når ingen kan eje vedligeholdelsen. Den første deploy er nem; året med vedligeholdelse bagefter er den virkelige omkostning.