HubSpot API-integrasjon for interne verktøy: en Node- og Python-guide (2026)

Leter du fortsatt etter en HubSpot API-nøkkel for å koble opp HubSpot API-integrasjonen din? Slutt å lete. HubSpot fjernet statiske API-nøkler 30. november 2022, og dagens Node-SDK (@hubspot/api-client, nå på v14) godtar uansett ikke en slik nøkkel. Riktig legitimasjon for et internt verktøy med én konto er et private app access token, og denne guiden bygger en ekte HubSpot-til-internverktøy-synkronisering i både Node og Python, fra ditt første create contact-kall til en signaturvalidert webhook.

Kort svar: En HubSpot API-integrasjon lar et internt verktøy lese og skrive CRM-data gjennom HubSpots v3 REST API. For et internt verktøy med én konto autentiserer du med et private app-token (HubSpot fjernet API-nøkler i 2022), og synkroniserer deretter endringer i sanntid med webhooks i stedet for polling.

Dette skal du bygge:

• Private app-token-autentisering, pluss ditt første create contact-kall i Node og Python
• En webhook-mottaker som validerer X-HubSpot-Signature-v3 før den stoler på nyttelasten
• En 429-sikker synkronisering i batcher på 100 til en intern ticketing- eller ERP-post

Hvordan fungerer HubSpot API-integrasjon for interne verktøy?

En HubSpot API-integrasjon kobler et internt verktøy (en ticketing-app, et ERP-system, et faktureringsdashboard, en kundeportal) til HubSpots CRM gjennom v3 REST API-et. Verktøyet ditt leser og skriver CRM-objekter (kontakter, avtaler, selskaper eller egendefinerte objekter) over HTTPS med et private app access token, og endringer i sanntid strømmer tilbake gjennom webhooks.

Tenk på HubSpots CRM som en database du snakker med over HTTP. Hver post er et objekt med en type og en ID. hubspot crm api integration-en du bygger gjør to jobber: den dytter data inn i HubSpot (oppretter en kontakt når en sak åpnes) og henter data ut av det (leser en avtale når det interne dashboardet ditt rendres).

Synkronisering går i én av to retninger. En enveis synkronisering kopierer endringer fra HubSpot til verktøyet ditt, eller fra verktøyet ditt til HubSpot. En toveis synkronisering gjør begge deler og trenger loop-beskyttelse, som vi kommer tilbake til senere. Og i stedet for å spørre HubSpot «noe nytt?» hvert minutt (polling), registrerer du en webhook slik at HubSpot varsler deg i det øyeblikket en post endres.

Hvis du heller vil eie dataene dine fullt og helt enn å integrere med et hostet CRM i det hele tatt, er det å selv-hoste et åpen kildekode-CRM en annen vei verdt å vurdere før du bestemmer deg. Men hvis HubSpot allerede er din kilde til sannhet, er API-et hvordan alt annet snakker med det.

For et internt verktøy med én konto trenger du verken OAuth eller en oppføring i app-markedsplassen. Et private app-token og en webhook er hele integrasjonen.

Autentisering i 2026: Hvorfor det ikke finnes noen HubSpot API-nøkkel lenger

For HubSpot API-autentisering på et internt verktøy med én konto bruker du et private app access token. Det er et statisk bearer-token du genererer én gang i HubSpot-kontoen din, avgrenset til nøyaktig de objektene verktøyet ditt trenger å røre. Det finnes ingen fornyelsesflyt og ingen utløpsdato. OAuth finnes for offentlige apper med flere kontoer, ikke for dashboardet driftsteamet ditt kjører internt.

Private app-token vs. den utfasede API-nøkkelen

Her er fellen som lurer halvparten av utviklerne som havner på dette søkeresultatet. HubSpot fjernet API-nøkler 30. november 2022, og de er fullstendig ustøttet nå. Autofullføring foreslår fortsatt «hubspot api key» fordi muskelminnet ikke har tatt innover seg endringen, men det finnes ingen nøkkel å hente. Gå for en hubspot private app i stedet: opprett den under Settings, gi den scopene den trenger, og kopier access-tokenet fra Auth-fanen. HubSpots oversikt over private apps dekker oppsettet.

To regler for selve tokenet. Gi minst mulig privilegium: hvis verktøyet ditt bare leser avtaler og skriver kontakter, ber du om crm.objects.contacts.write og crm.objects.deals.read, ikke mer. Og oppbevar tokenet i en miljøvariabel eller en secret manager, sendt i Authorization: Bearer-headeren, aldri hardkodet og aldri sendt til nettleseren.

Konklusjonen er enkel. For et internt verktøy, bruk et private app access token. Gå for OAuth bare hvis dette senere blir en offentlig app med flere kontoer som andre selskaper installerer i sine egne portaler.

Ditt første HubSpot API-kall: opprett en kontakt i Node og Python

Det klassiske første kallet er create contact, og de offisielle SDK-ene gjør det til noen få linjer. Installer klienten, initialiser den med private app-tokenet ditt fra miljøet, opprett så en kontakt og les tilbake en avtale. Dette er samme mønster du kommer til å gjenbruke for selskaper, saker og hubspot custom objects api-kall — bare objekttypen endrer seg.

Her er Node-versjonen med @hubspot/api-client (v14):

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

// Private app-token fra en secret manager eller miljøvariabel, aldri hardkodet
const hubspot = new Client({ accessToken: process.env.HUBSPOT_PRIVATE_APP_TOKEN });

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

// Les en avtale basert på 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 fra miljøet, ikke fra versjonskontroll
client = HubSpot(access_token=os.environ["HUBSPOT_PRIVATE_APP_TOKEN"])

# Opprett en kontakt
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)

# Les en avtale basert på 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-tips: test mot en HubSpot developer sandbox, aldri produksjon først. Et feilformet create-kall i produksjon etterlater ekte søppelposter salgsteamet ditt må rydde opp i. Tokenet, scopene og objektmodellen oppfører seg identisk i sandkassen.

Hvordan synkroniserer du HubSpot med et internt verktøy i sanntid?

Bruk webhooks, ikke polling. Registrer et webhook-abonnement i private app-en din for objektet og hendelsen du er interessert i (for eksempel deal.propertyChange), pek det mot et HTTPS-endepunkt du hoster, så POSTer HubSpot deg et lite JSON-array i det øyeblikket en matchende endring skjer. Bruk polling bare når det ikke finnes noe abonnement for det du trenger å overvåke.

Gevinsten er effektivitet. Polling spør «noe nytt?» hvert minutt og brenner av rate limit-en din mens den gjør det; en webhook forteller deg bare i det øyeblikket en avtale endres. Den forskjellen betyr noe når du skalerer, og webhooks er mainstream nå, ikke eksotisk: Postmans 2025 State of the API Report, en undersøkelse blant over 5 700 utviklere, fant at rundt halvparten av teamene bruker dem.

Registrer abonnementet under Webhooks-fanen i private app-en din, sett mål-URL-en, og velg hendelsene. HubSpot sender et array av hendelsesobjekter, hver med subscriptionType, objectId, og hva som ble endret. Her er en enkel mottaker i Node med Express:

import express from "express";

const app = express();
// Fang opp rå-body: du trenger de eksakte bytene for å validere signaturen i neste steg
app.use(express.json({
  verify: (req, _res, buf) => { req.rawBody = buf.toString("utf8"); },
}));

// HubSpot POSTer et array av hendelser til denne URL-en
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);
    // IKKE stol på denne nyttelasten ennå. Neste seksjon validerer den før vi handler.
  }
  res.sendStatus(200);
});

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

Dette er der byggeprosessen blir konkret. Si at du synkroniserer en avtale inn i en liten produsents ERP-post: webhooken utløses, håndtereren din oppretter eller oppdaterer den matchende ERP-saken, og driftsteamet ditt ser endringen uten å røre HubSpot. Det er samme sanntidstilnærming vi bruker for å synkronisere en talebasert AI-agent mot et CRM, bare at triggeren er en egenskapsendring i stedet for en telefonsamtale. Én advarsel: stubben over stoler på alt som POSTes til den. Fiks det før du går i produksjon.

Validering av webhook-signaturer (v3) så du aldri stoler på en forfalsket nyttelast

Valider hver innkommende webhook med v3-signaturen. HubSpot signerer hver forespørsel med app-hemmeligheten din og sender to headere, X-HubSpot-Signature-v3 og X-HubSpot-Request-Timestamp. Avvis alt som er eldre enn 5 minutter, gjenoppbygg kildestrengen som metode + full URL + rå body + tidsstempel, HMAC-SHA256 den med app-hemmeligheten, base64-enkod, og sammenlign i konstant tid.

Hvis du hopper over dette, kan hvem som helst som gjetter webhook-URL-en din forfalske en avtaleoppdatering. Validering er ikke valgfritt. HubSpots dokumentasjon om å validere forespørsler og changeloggen for v3-signaturer beskriver oppskriften i detalj. Her er den som ferdig Express-middleware:

import crypto from "crypto";

const CLIENT_SECRET = process.env.HUBSPOT_APP_SECRET; // fra innstillingene til private app-en din
const MAX_AGE_MS = 5 * 60 * 1000; // avvis alt som er eldre enn 5 minutter

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

  // 1. Avvis foreldede forespørsler (replay-beskyttelse)
  if (!signature || !timestamp || Date.now() - Number(timestamp) > MAX_AGE_MS) {
    return res.sendStatus(401);
  }

  // 2. Gjenoppbygg den eksakte kildestrengen: metode + full URL + rå body + tidsstempel
  const uri = `https://${req.get("host")}${req.originalUrl}`;
  const source = `${req.method}${uri}${req.rawBody}${timestamp}`;

  // 3. HMAC-SHA256 med app-hemmeligheten, base64-enkodet
  const hash = crypto
    .createHmac("sha256", CLIENT_SECRET)
    .update(source, "utf8")
    .digest("base64");

  // 4. Konstant-tid-sammenligning mot headeren
  const expected = Buffer.from(hash);
  const received = Buffer.from(signature);
  if (expected.length !== received.length ||
      !crypto.timingSafeEqual(expected, received)) {
    return res.sendStatus(401);
  }
  next();
}

Samme sjekk som en Python-funksjon, slik at begge stackene er dekket:

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 minutter

def is_valid_signature(method, uri, body, signature, timestamp):
    # 1. Avvis foreldede forespørsler
    if not signature or not timestamp:
        return False
    if int(time.time() * 1000) - int(timestamp) > MAX_AGE_MS:
        return False

    # 2. metode + full URL + rå body + tidsstempel
    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. Sammenligning i konstant tid
    return hmac.compare_digest(expected, signature)

Fellen som koster folk en ettermiddag: HubSpot signerer den fullstendige mål-URL-en, skjema, host og sti samlet. Bak en proxy, en load balancer eller en ngrok-tunnel kan req.get("host") rapportere den interne hosten i stedet for den offentlige HubSpot signerte. Hvis valideringen fortsetter å feile på en nyttelast du er sikker på er legitim, logg den eksakte URI-en du bygde opp og sammenlign den med den offentlige webhook-URL-en din, tegn for tegn.

Rate limits, 429-feil og batch-API-et: hva vi kjørte i produksjon

Private apps får omtrent 10 forespørsler per sekund (100 per 10 sekunder på Free/Starter, 190 per 10 sekunder på Pro/Enterprise) med et daglig tak mellom 250 000 og 1 000 000. Fellen: CRM Search har et eget tak på 4 forespørsler per sekund, og batch-endepunkter godtar maksimalt 100 poster per forespørsel. HubSpots bruksretningslinjer lister opp nivåene.

Her møtte teorien et rødt staging-dashboard. Under en backfill denne våren dyttet vi rundt 8 000 eksisterende poster inn i HubSpot fra et internt ticketing-verktøy og beriket hver av dem med et CRM Search-oppslag. Vi kjørte @hubspot/api-client v14 på Node-siden og hubspot-api-client v12 for en Python-berikelsesarbeider. Bulk-skrivingen gikk fint. Search-kallene falt sammen på under et minutt, fordi arbeideren vår fyrte av Search i rundt 15 forespørsler/s mot et hardt tak på 4 forespørsler/s vi ikke hadde budsjettert med separat.

To endringer fikset det. Først, en retry-wrapper som leser X-HubSpot-RateLimit-*-responsheaderne og trekker seg tilbake ved en 429:

// Pakk inn ethvert HubSpot-kall; prøver på nytt ved 429 med eksponentiell 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;

      // Respekter HubSpots reset-vindu hvis headeren er til stede
      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 andre sluttet vi å skrive poster én om gangen. Batch-endepunktet tar opptil 100 poster per POST /crm/v3/objects/{objectType}/batch/create, så vi delte backfillen opp i 80 batch-kall i stedet for 8 000 enkelt-POST-er:

// HubSpots batch-endepunkter godtar maksimalt 100 poster per forespørsel
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, delt opp i 100 om gangen
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`);
  }
}

Å begrense Search-arbeideren til 4 forespørsler/s og batche skrivingen gjorde at en kjøring som druknet i retries, i stedet ble ferdig i stillhet. Hvis du husker ett tall fra denne seksjonen, la det være 4: CRM Search-taket er grensen som biter i produksjon, og det er den ingen oversiktsartikler nevner. Det gamle batch-taket på «10 for kontakter», forresten, er borte; dagens tak er 100 på tvers av objekttyper.

Toveis synkronisering: å skrive endringer tilbake til HubSpot uten uendelige løkker

En toveis synkronisering skriver endringer tilbake til HubSpot fra det interne verktøyet ditt, i tillegg til å lese dem inn. Faren er en feedback-loop: tilbakeskrivingen din utløser den samme webhooken som startet håndtereren din, som skriver igjen, i det uendelige. Forhindre det med en idempotensnøkkel (hopp over endringer du allerede har brukt) og et kildeflagg (ignorer innkommende hendelser ditt eget verktøy forårsaket).

const processed = new Set(); // bruk Redis eller en unik DB-constraint i produksjon

async function writeBackToHubSpot(record) {
  // Dedup-nøkkel: objekt-ID + en hash av endringen vi er i ferd med å bruke
  const key = `${record.id}:${record.updatedHash}`;
  if (processed.has(key)) return; // allerede synkronisert denne eksakte endringen
  processed.add(key);

  await withRetry(() =>
    hubspot.crm.contacts.basicApi.update(record.id, {
      // Merk kilden slik at den resulterende webhooken ignoreres av vår egen mottaker
      // (sjekk for source: "internal-tool" før du handler på en innkommende hendelse)
      properties: { internal_status: record.status, last_sync_source: "internal-tool" },
    })
  );
}

Mønsteret er lite, men å hoppe over det er hvordan en synkronisering stille dobler skrivevolumet ditt over natten. Når dataene er rene i begge retninger, mater teamene dem ofte videre nedstrøms inn i en AI SDR-pipeline eller et rapporteringslag. Nangos tutorial for HubSpot-integrasjon er en solid, Node-only-referanse hvis du vil ha et annet perspektiv på toveis synkronisering, men du må porte loop-beskyttelsesideen selv.

Bør du bygge dette selv, eller leie inn en integrasjonspartner?

Bygg selv når synkroniseringen er liten, stabil og eid: en enveis flyt, en håndfull objekter, og en utvikler som kan absorbere HubSpots omtrent to årlige brytende endringer. Leie inn en partner når du trenger toveis synkronisering, modellering av egendefinerte objekter, eller når ingen i teamet kan eie løpende vedlikehold. Den avgjørende faktoren er sjelden selve den første byggingen; det er hvem som passer på den om et år.

Her er en ærlig sjekkliste. Bygg det selv hvis: retningen er enveis, du synkroniserer standardobjekter, du har en utvikler som kan hoste et webhook-endepunkt, og noen vil merke det når en nyttelast begynner å feile. Alt over er blueprinten din.

Leie inn en partner hvis: du trenger toveis synkronisering med loop-beskyttelse på tvers av flere objekter, du modellerer egendefinerte objekter med typede assosiasjoner, du kobler sammen flere systemer (HubSpot pluss et ERP-system pluss fakturering), eller personen som skulle vedlikeholde det allerede er fullt belastet. HubSpot bruker datobasert API-versjonering med brytende endringer bare rundt to ganger i året, noe som høres mildt ut helt til en lander midt i din travleste uke og det ikke finnes noen eier. Den vedlikeholdshalen, ikke den første utrullingen, er det som stille senker interne integrasjoner. Hvis du heller ikke vil eie den selv, er det der våre tjenester for egendefinert CRM-integrasjon kommer inn.

Viktigste punkter

• Det finnes ikke lenger noen HubSpot API-nøkkel. Bruk et private app access token for et internt verktøy med én konto; OAuth er kun for offentlige apper med flere kontoer.
• Valider alltid X-HubSpot-Signature-v3 før du stoler på en webhook-nyttelast. Gjenoppbygg kildestrengen med den fullstendige mål-URL-en.
• Respekter taket på 4 forespørsler/s for CRM Search og batch store skrivinger i biter på 100 med 429-backoff.
• Foretrekk webhooks fremfor polling for sanntidssynkronisering, og en HubSpot-integrasjon er bare én brikke i en bredere AI-verktøy for bedrifter-stack.

Sitter du fast på vedlikeholdssiden, eller vil du ha et ekstra sett øyne før du skipper koden? Book en gratis integrasjonskonsultasjon. Ingen press uansett; koden over er din å kjøre uavhengig av hva du velger.

Ofte stilte spørsmål

Trenger jeg fortsatt en HubSpot API-nøkkel i 2026?

Nei. HubSpot fjernet statiske API-nøkler 30. november 2022, og de er fullstendig ustøttet. Autofullføring foreslår fortsatt «hubspot api key» av gammel vane, men det er ingenting å hente. For et internt verktøy med én konto, opprett en private app under Settings og bruk dens access-token i stedet.

Hva er forskjellen mellom et private app-token og OAuth for HubSpot?

Et private app access token er en statisk legitimasjon for én enkelt HubSpot-konto, uten utløpsdato og uten fornyelsesflyt, ideelt for et internt verktøy. OAuth 2.0 er for offentlige apper med flere kontoer som andre selskaper installerer i sine egne portaler; tokenene utløper etter rundt seks timer og krever en fornyelsessyklus.

Hva er HubSpots API-rate limits i 2026?

Private apps får rundt 10 forespørsler per sekund (100 per 10 sekunder på Free/Starter, 190 på Pro/Enterprise) med et daglig tak på 250 000 til 1 000 000. CRM Search-API-et har et eget tak på 4 forespørsler per sekund, og batch-endepunkter godtar maksimalt 100 poster per forespørsel.

Hvordan validerer jeg en HubSpot webhook-signatur?

Bruk v3-oppskriften: avvis forespørsler der X-HubSpot-Request-Timestamp er eldre enn fem minutter, bygg deretter en kildestreng av metode pluss full mål-URL pluss rå body pluss tidsstempel. HMAC-SHA256 den med app-hemmeligheten din, base64-enkod resultatet, og sammenlign det med X-HubSpot-Signature-v3 i konstant tid.

Hvilken HubSpot-SDK bør jeg bruke, Node eller Python?

Begge er offisielle og vedlikeholdte. Node bruker @hubspot/api-client (v14) og Python bruker hubspot-api-client (v12). De eksponerer samme v3 CRM-objektmodell, så velg den som passer stacken din. Denne guiden leverer identisk autentiserings- og signaturvalideringskode i begge språkene.

Hvordan synkroniserer jeg HubSpot med et internt verktøy i sanntid?

Registrer et webhook-abonnement i private app-en din for objektet og hendelsen du er interessert i, og host deretter et HTTPS-endepunkt HubSpot POSTer til når en matchende endring skjer. Valider signaturen, og skriv deretter endringen inn i det interne verktøyet ditt. Bruk polling bare når ingen webhook-abonnement dekker det du trenger.

Hva er en HubSpot Service Key, og bør jeg bruke den?

En Service Key er en kontonivå-legitimasjon for data-only-bruk, som HubSpot satte i offentlig beta i februar 2026. Den er rettet mot server-side jobber som bare rører data. For et standard internt verktøy i dag er et private app access token fortsatt den tryggere, bedre dokumenterte standarden; behandle Service Keys som beta helt til de er ferdig utviklet.

Kan jeg teste en HubSpot-integrasjon uten å røre produksjon?

Ja. Opprett en HubSpot developer sandbox og pek private app-tokenet ditt mot den. Scopene, objektmodellen, webhooks og rate limits oppfører seg likt som i produksjon, så du kan opprette testkontakter og utløse webhooks uten å etterlate søppelposter salgsteamet ditt må rydde opp i senere.

Hvor mange poster kan HubSpots batch-API ta imot samtidig?

Batch-endepunktene (POST /crm/v3/objects/{objectType}/batch/create og søsknene update og upsert) godtar maksimalt 100 poster per forespørsel. Del opp større nyttelaster i grupper på 100. Det gamle taket på «10 poster for kontakter» som enkelte tutorials fortsatt siterer, er fjernet; 100 er dagens tall på tvers av objekttyper.

Bør jeg bygge dette selv, eller leie inn et byrå?

Bygg selv når synkroniseringen er enveis, bruker standardobjekter, og har en eier som kan absorbere HubSpots to årlige brytende endringer. Leie inn en partner for toveis synkronisering, modellering av egendefinerte objekter, eller når ingen kan eie vedlikeholdet. Den første utrullingen er enkel; året med vedlikehold etterpå er den egentlige kostnaden.