HubSpot API-integratie voor Aangepaste Interne Tools: een Node + Python-gids (2026)

HubSpot API-integratie voor Aangepaste Interne Tools: een Node + Python-gids (2026)

Ben je nog steeds op zoek naar een HubSpot API key om je HubSpot API-integratie aan te sluiten? Stop met zoeken. HubSpot heeft statische API keys op 30 november 2022 afgeschaft, en de huidige Node SDK (@hubspot/api-client, inmiddels v14) accepteert er sowieso geen. De juiste credential voor een interne tool met één account is een private app access token, en deze gids bouwt een echte HubSpot-naar-interne-tool sync in zowel Node als Python, van je eerste create contact-aanroep tot een signature-gevalideerde webhook.

Kort antwoord: Een HubSpot API-integratie laat een aangepaste interne tool CRM-data lezen en schrijven via HubSpot's v3 REST API. Voor een interne tool met één account authenticeer je met een private app access token (HubSpot heeft API keys in 2022 afgeschaft), en synchroniseer je wijzigingen vervolgens realtime met webhooks in plaats van polling.

Dit ga je bouwen:

• Private-app-token-authenticatie plus je eerste create contact-aanroep in Node en Python
• Een webhook-ontvanger die X-HubSpot-Signature-v3 valideert voordat hij een payload vertrouwt
• Een 429-veilige, batch-100 sync naar een intern ticketing- of ERP-record

Hoe Werkt een HubSpot API-integratie voor Aangepaste Interne Tools?

Een HubSpot API-integratie verbindt een aangepaste interne tool (een ticketing-app, een ERP, een facturatiedashboard, een klantenportaal) met HubSpot's CRM via de v3 REST API. Je tool leest en schrijft CRM-objecten (contacts, deals, companies of custom objects) over HTTPS met een private app access token, en realtime wijzigingen stromen terug via webhooks.

Zie HubSpot's CRM als een database waarmee je over HTTP praat. Elk record is een object met een type en een ID. De hubspot crm api-integratie die je bouwt doet twee dingen: hij duwt data naar HubSpot (een contact aanmaken zodra een ticket opent) en haalt er data uit (een deal uitlezen wanneer je interne dashboard rendert).

Sync verloopt in een van twee richtingen. Een one-way sync kopieert wijzigingen van HubSpot naar je tool, of van je tool naar HubSpot. Een two-way sync doet beide en heeft loop-bescherming nodig, wat we later behandelen. En in plaats van HubSpot elke minuut te vragen "iets nieuws?" (polling), registreer je een webhook zodat HubSpot je meteen laat weten zodra een record verandert.

Als je liever volledige controle over je data hebt dan een gehost CRM te integreren, is het zelf hosten van een open-source CRM een ander pad dat de moeite waard is om te overwegen voordat je je vastlegt. Maar als HubSpot al je single source of truth is, is de API hoe al het andere ermee praat.

Voor een interne tool met één account heb je geen OAuth of een vermelding in de app-marketplace nodig. Een private app token en een webhook zijn de hele integratie.

Authenticatie in 2026: Waarom er Geen HubSpot API Key Meer Is

Gebruik voor HubSpot API-authenticatie op een interne tool met één account een private app access token. Het is een statische bearer token die je één keer genereert in je HubSpot-account, met scopes die exact aansluiten op de objecten die je tool aanraakt. Er is geen refresh-flow en geen verloopdatum. OAuth bestaat voor publieke apps met meerdere accounts, niet voor het dashboard dat je ops-team intern draait.

Private App Token versus de Verouderde API Key

Dit is de valkuil waar de helft van de developers die deze zoekresultatenpagina bereiken intrapt. HubSpot heeft API keys op 30 november 2022 afgeschaft, en ze worden nu volledig niet meer ondersteund. Autocomplete suggereert nog steeds "hubspot api key" omdat het spiergeheugen het nog niet heeft bijgebeend, maar er is geen key om op te halen. Grijp in plaats daarvan naar een hubspot private app: maak hem aan in Settings, geef hem de scopes die hij nodig heeft, en kopieer de access token van het tabblad Auth. HubSpot's overzicht van private apps behandelt de setup.

Twee regels voor de token zelf. Geef least privilege: als je tool alleen deals leest en contacts schrijft, vraag dan crm.objects.contacts.write en crm.objects.deals.read aan, niets meer. En bewaar de token in een environment variable of een secret manager, verzonden in de Authorization: Bearer-header, nooit hardcoded en nooit meegestuurd naar de browser.

Het oordeel is simpel. Gebruik voor een interne tool een private app access token. Grijp alleen naar OAuth als dit later een publieke, multi-account app wordt die andere bedrijven in hun eigen portals installeren.

Je Eerste HubSpot API-aanroep: een Contact Aanmaken in Node en Python

De klassieke eerste aanroep is create contact, en de officiële SDK's maken er een paar regels code van. Installeer de client, initialiseer hem met je private app token uit de environment, maak dan een contact aan en lees een deal terug. Dit is hetzelfde patroon dat je hergebruikt voor companies, tickets en hubspot custom objects api-aanroepen, alleen het objecttype verandert.

Hier is de Node-versie met @hubspot/api-client (v14):

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

// Private app token uit een secret manager of env var, nooit hardcoded
const hubspot = new Client({ accessToken: process.env.HUBSPOT_PRIVATE_APP_TOKEN });

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

// Lees een deal op via ID
const deal = await hubspot.crm.deals.basicApi.getById(
  "1234567890",
  ["dealname", "amount", "dealstage"],
);
console.log(deal.properties.dealname, deal.properties.amount);

En hetzelfde in Python met 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 uit de environment, niet in source control
client = HubSpot(access_token=os.environ["HUBSPOT_PRIVATE_APP_TOKEN"])

# Maak een contact aan
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)

# Lees een deal op via 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 tegen een HubSpot developer sandbox, nooit eerst tegen productie. Een misvormde create-aanroep in productie laat echte rommelrecords achter die je salesteam moet opruimen. De token, scopes en het objectmodel gedragen zich in de sandbox identiek.

Hoe Synchroniseer je HubSpot Realtime met een Interne Tool?

Gebruik webhooks, geen polling. Registreer een webhook-subscription in je private app voor het object en de gebeurtenis waar het je om gaat (bijvoorbeeld deal.propertyChange), wijs hem naar een HTTPS-endpoint dat je zelf host, en HubSpot post't je een kleine JSON-array zodra een bijpassende wijziging plaatsvindt. Poll alleen wanneer er geen subscription bestaat voor wat je moet volgen.

De winst zit in efficiëntie. Polling vraagt elke minuut "iets nieuws?" en verbrandt daarbij je rate limit; een webhook vertelt je gewoon het moment waarop een deal verandert. Dat verschil telt op schaal, en webhooks zijn inmiddels mainstream, niet exotisch: Postman's 2025 State of the API Report, een enquête onder meer dan 5.700 developers, vond dat ruwweg de helft van de teams erop vertrouwt.

Registreer de subscription onder het tabblad Webhooks van je private app, stel de target-URL in en kies de events. HubSpot stuurt een array van event-objecten, elk met de subscriptionType, de objectId en wat er is veranderd. Hier is een receiver-stub in Node met Express:

import express from "express";

const app = express();
// Leg de raw body vast: je hebt de exacte bytes nodig om de signature hierna te valideren
app.use(express.json({
  verify: (req, _res, buf) => { req.rawBody = buf.toString("utf8"); },
}));

// HubSpot post't een array van events naar deze 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);
    // Vertrouw deze payload nog NIET. De volgende sectie valideert hem voordat we handelen.
  }
  res.sendStatus(200);
});

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

Dit is waar het concreet wordt. Stel dat je een deal synchroniseert naar het ERP-record van een kleine producent: de webhook vuurt, je handler maakt of update het bijpassende ERP-ticket, en je ops-team ziet de wijziging zonder HubSpot aan te raken. Het is dezelfde realtime aanpak die we gebruiken om een voice agent te synchroniseren met een CRM, alleen is de trigger een property-wijziging in plaats van een telefoongesprek. Eén waarschuwing: die stub hierboven vertrouwt alles wat er met een POST naar binnenkomt. Fix dat voordat je live gaat.

Webhook-signatures Valideren (v3), zodat je Nooit een Vervalste Payload Vertrouwt

Valideer elke inkomende webhook met de v3-signature. HubSpot ondertekent elk verzoek met je app secret en stuurt twee headers mee, X-HubSpot-Signature-v3 en X-HubSpot-Request-Timestamp. Wijs alles ouder dan 5 minuten af, herbouw de source string als method + volledige URL + raw body + timestamp, pas er HMAC-SHA256 op toe met het app secret, base64-encodeer het resultaat, en vergelijk in constante tijd.

Sla je dit over, dan kan iedereen die je webhook-URL raadt een deal-update vervalsen. Validatie is niet optioneel. HubSpot's documentatie over het valideren van requests en de changelog van v3-signatures leggen het exacte recept haarfijn uit. Hier is het als drop-in Express-middleware:

import crypto from "crypto";

const CLIENT_SECRET = process.env.HUBSPOT_APP_SECRET; // uit je private-app-instellingen
const MAX_AGE_MS = 5 * 60 * 1000; // wijs alles ouder dan 5 minuten af

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

  // 1. Wijs verouderde requests af (replay-bescherming)
  if (!signature || !timestamp || Date.now() - Number(timestamp) > MAX_AGE_MS) {
    return res.sendStatus(401);
  }

  // 2. Herbouw de exacte source string: method + volledige URL + raw body + timestamp
  const uri = `https://${req.get("host")}${req.originalUrl}`;
  const source = `${req.method}${uri}${req.rawBody}${timestamp}`;

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

  // 4. Vergelijk in constante tijd met de 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();
}

Dezelfde check als Python-functie, zodat beide stacks gedekt zijn:

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. Wijs verouderde requests af
    if not signature or not timestamp:
        return False
    if int(time.time() * 1000) - int(timestamp) > MAX_AGE_MS:
        return False

    # 2. method + volledige 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. Vergelijking in constante tijd
    return hmac.compare_digest(expected, signature)

De valkuil die mensen een middag kost: HubSpot ondertekent de volledige doel-URL, scheme, host en path samen. Achter een proxy, een load balancer of een ngrok-tunnel kan req.get("host") de interne host teruggeven in plaats van de publieke host die HubSpot heeft ondertekend. Blijft validatie falen op een payload waarvan je zeker weet dat hij legitiem is, log dan de exacte URI die je hebt herbouwd en vergelijk hem teken voor teken met je publieke webhook-URL.

Rate Limits, 429's en de Batch-API: Wat we in Productie Draaiden

Private apps krijgen ruwweg 10 requests per seconde (100 per 10 seconden op Free/Starter, 190 per 10 seconden op Pro/Enterprise) met een dagelijkse cap tussen 250.000 en 1.000.000. De valkuil: CRM Search heeft een aparte cap van 4 requests per seconde, en batch-endpoints accepteren maximaal 100 records per request. HubSpot's usage guidelines geven de tiers weer.

Hier ontmoette de theorie een rood staging-dashboard. Tijdens een backfill deze lente pushten we ruwweg 8.000 bestaande records naar HubSpot vanuit een interne ticketing-tool en verrijkten we elk record met een CRM Search-lookup. We draaiden @hubspot/api-client v14 aan de Node-kant en hubspot-api-client v12 voor een Python-verrijkingsworker. De bulk-writes gingen prima. De Search-aanroepen vielen binnen een minuut om, omdat onze worker Search afvuurde met rond de 15 req/s tegen een harde limiet van 4 req/s waar we apart geen rekening mee hadden gehouden.

Twee aanpassingen losten het op. Eerst een retry-wrapper die de X-HubSpot-RateLimit-* response-headers uitleest en terugvalt bij een 429:

// Wrap elke HubSpot-aanroep; retryt bij een 429 met exponentiële 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;

      // Respecteer HubSpot's reset-window als de header aanwezig is
      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++;
    }
  }
}

Ten tweede stopten we met records één voor één schrijven. Het batch-endpoint verwerkt tot 100 records per POST /crm/v3/objects/{objectType}/batch/create, dus knipten we de backfill op in 80 batch-aanroepen in plaats van 8.000 losse POSTs:

// HubSpot batch-endpoints accepteren maximaal 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, opgeknipt in stukken van 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`);
  }
}

Door de Search-worker te begrenzen op 4 req/s en de writes te batchen, werd een run die verdronk in retries er eentje die stilletjes afrondde. Als je één getal uit deze sectie onthoudt, laat het 4 zijn: de CRM Search-cap is de limiet die in productie bijt, en het is degene die elke overzichtspost vergeet te noemen. De oude batch-limiet van "10 voor contacts" is overigens verdwenen; de huidige limiet is 100, over alle objecttypes heen.

Two-way Gaan: Wijzigingen Terugschrijven naar HubSpot Zonder Oneindige Loops

Een two-way sync schrijft wijzigingen terug naar HubSpot vanuit je interne tool, naast dat hij ze inleest. Het gevaar is een feedbackloop: je write-back triggert precies de webhook die je handler heeft afgevuurd, die opnieuw schrijft, voor altijd. Voorkom dit met een idempotency key (sla wijzigingen over die je al hebt toegepast) en een source-flag (negeer inkomende events die je eigen tool heeft veroorzaakt).

const processed = new Set(); // gebruik Redis of een unieke DB-constraint in productie

async function writeBackToHubSpot(record) {
  // Dedup-key: object-id + een hash van de wijziging die we gaan toepassen
  const key = `${record.id}:${record.updatedHash}`;
  if (processed.has(key)) return; // deze exacte wijziging is al gesynchroniseerd
  processed.add(key);

  await withRetry(() =>
    hubspot.crm.contacts.basicApi.update(record.id, {
      // Tag de source zodat de resulterende webhook door onze eigen ontvanger wordt genegeerd
      // (controleer op source: "internal-tool" voordat je op een inkomend event handelt)
      properties: { internal_status: record.status, last_sync_source: "internal-tool" },
    })
  );
}

Het patroon is klein, maar door het over te slaan verdubbelt een sync in stilte je schrijfvolume in één nacht. Zodra de data in beide richtingen schoon is, voeren teams het vaak stroomafwaarts in een AI SDR-pipeline of een rapportagelaag. Nango's HubSpot-integratietutorial is een solide, Node-only referentie als je een tweede kijk op two-way sync wilt, al moet je het loop-preventie-idee zelf overzetten.

Zelf Bouwen of een Integratiepartner Inhuren?

Bouw het zelf wanneer de sync klein, stabiel en geborgd is: een one-way flow, een handvol objecten, en een engineer die HubSpot's ruwweg tweemaal per jaar optredende breaking changes kan opvangen. Huur een partner in wanneer je bidirectionele sync nodig hebt, custom-object-modellering, of wanneer niemand in het team het lopende onderhoud kan dragen. De beslissende factor is zelden de eerste build; het is wie er over een jaar nog naar kijkt.

Hier is een eerlijke checklist. Bouw het zelf als: de richting one-way is, je standaardobjecten synchroniseert, je een developer hebt die een webhook-endpoint kan hosten, en iemand het merkt zodra een payload begint te falen. Alles hierboven is jouw blauwdruk.

Huur een partner in als: je two-way sync met loop-preventie nodig hebt over meerdere objecten, je custom objects modelleert met getypeerde associations, je meerdere systemen aan elkaar knoopt (HubSpot plus een ERP plus facturatie), of de persoon die het zou onderhouden al aan zijn taks zit. HubSpot gebruikt datum-gebaseerde API-versionering met breaking changes zo'n twee keer per jaar, wat mild klinkt totdat er een landt in je drukste week en er geen eigenaar is. Die onderhoudsstaart, niet de eerste deploy, is wat interne integraties stilletjes de das omdoet. Wil je dit liever niet zelf dragen, dan komen onze aangepaste CRM-integratiediensten in beeld.

Kernpunten

• Er is geen HubSpot API key meer. Gebruik een private app access token voor een interne tool met één account; OAuth is alleen voor publieke, multi-account apps.
• Valideer altijd X-HubSpot-Signature-v3 voordat je een webhook-payload vertrouwt. Herbouw de source string met de volledige doel-URL.
• Respecteer de cap van 4 req/s voor CRM Search en batch grote writes in stukken van 100 met een 429-backoff.
• Geef de voorkeur aan webhooks boven polling voor realtime sync, en een HubSpot-integratie is één onderdeel van een bredere AI-tools voor bedrijven-stack.

Loop je vast op het onderhoudsvlak, of wil je een tweede paar ogen voordat je live gaat? Boek een gratis integratieconsult. Geen druk in beide gevallen; de code hierboven is sowieso van jou om te draaien.

Veelgestelde Vragen

Heb ik in 2026 nog een HubSpot API key nodig?

Nee. HubSpot heeft statische API keys op 30 november 2022 afgeschaft, en ze worden volledig niet meer ondersteund. Autocomplete suggereert uit gewoonte nog steeds "hubspot api key", maar er is niets om op te halen. Maak voor een interne tool met één account in plaats daarvan een private app aan in Settings en gebruik de access token daarvan.

Wat is het verschil tussen een private app token en OAuth voor HubSpot?

Een private app access token is een statische credential voor één HubSpot-account, zonder verloopdatum en zonder refresh-flow, ideaal voor een interne tool. OAuth 2.0 is voor publieke, multi-account apps die andere bedrijven in hun eigen portals installeren; de tokens verlopen na ongeveer zes uur en vereisen een refresh-cyclus.

Wat zijn HubSpot's API-rate limits in 2026?

Private apps krijgen ongeveer 10 requests per seconde (100 per 10 seconden op Free/Starter, 190 op Pro/Enterprise) met een dagelijkse cap van 250.000 tot 1.000.000. De CRM Search-API heeft een aparte cap van 4 requests per seconde, en batch-endpoints accepteren maximaal 100 records per request.

Hoe valideer ik een HubSpot-webhooksignature?

Gebruik het v3-recept: wijs requests af waar X-HubSpot-Request-Timestamp ouder is dan vijf minuten, bouw dan een source string van method plus volledige doel-URL plus raw body plus timestamp. Pas er HMAC-SHA256 op toe met je app secret, base64-encodeer het resultaat, en vergelijk het in constante tijd met X-HubSpot-Signature-v3.

Welke HubSpot-SDK moet ik gebruiken, Node of Python?

Beide zijn officieel en worden onderhouden. Node gebruikt @hubspot/api-client (v14) en Python gebruikt hubspot-api-client (v12). Ze bieden hetzelfde v3 CRM-objectmodel, dus kies wat past bij jouw stack. Deze gids levert identieke auth- en signature-validatiecode in beide talen.

Hoe synchroniseer ik HubSpot realtime met een aangepaste interne tool?

Registreer een webhook-subscription in je private app voor het object en de gebeurtenis waar het je om gaat, en host vervolgens een HTTPS-endpoint waar HubSpot naartoe post't zodra een bijpassende wijziging plaatsvindt. Valideer de signature, en schrijf de wijziging vervolgens in je interne tool. Poll alleen wanneer geen enkele webhook-subscription dekt wat je nodig hebt.

Wat is een HubSpot Service Key en moet ik hem gebruiken?

Een Service Key is een account-niveau, data-only credential die HubSpot in februari 2026 in publieke bèta heeft gezet. Hij is gericht op serverside jobs die alleen data aanraken. Voor een standaard interne tool vandaag is een private app access token nog steeds de veiligere, beter gedocumenteerde standaard; behandel Service Keys als bèta totdat ze afstuderen.

Kan ik een HubSpot-integratie testen zonder productie aan te raken?

Ja. Maak een HubSpot developer sandbox aan en wijs je private app token ernaartoe. De scopes, het objectmodel, de webhooks en de rate limits gedragen zich hetzelfde als in productie, dus je kunt testcontacten aanmaken en webhooks afvuren zonder rommelrecords achter te laten die je salesteam later moet opruimen.

Hoeveel records kan de HubSpot batch-API in één keer verwerken?

De batch-endpoints (POST /crm/v3/objects/{objectType}/batch/create en de update- en upsert-varianten ervan) accepteren maximaal 100 records per request. Knip grotere payloads op in groepen van 100. De oudere limiet van "10 records voor contacts" die sommige tutorials nog aanhalen, is verwijderd; 100 is de huidige limiet, over alle objecttypes heen.

Moet ik dit zelf bouwen of een bureau inhuren?

Bouw het zelf wanneer de sync one-way is, standaardobjecten gebruikt, en een eigenaar heeft die HubSpot's tweemaal-per-jaar breaking changes kan opvangen. Huur een partner in voor bidirectionele sync, custom-object-modellering, of wanneer niemand het onderhoud kan dragen. De eerste deploy is makkelijk; het jaar aan onderhoud daarna is de echte kostenpost.