Checklist voor een audit van legacy HubSpot-integraties: vind elke API-call, app en bedrijfsafhankelijkheid
Door Robin Laseur
Een checklist voor een HubSpot API-audit moet meer opleveren dan een lijst verouderde endpoints. Hij moet elke API-call koppelen aan de app-architectuur, de credential, de broncode, de eigenaar, het bedrijfsproces, de status van de vervanging en het testbewijs. Het resultaat is een inventaris waarmee je de migratie kunt plannen, en die technische en zakelijke teams samen kunnen doornemen.
De overgang die HubSpot in 2027 doorvoert, geeft de meeste bedrijven tijd om te migreren. Maar ze legt ook een bekend probleem bloot: de integraties die er het meest toe doen, zijn niet altijd de best gedocumenteerde. Een token kan in middleware zitten. Een geplande job draait misschien één keer per kwartaal. Eén endpoint kan ongemerkt de routering van leads, rapportages of ordersynchronisatie dragen.
Deze checklist brengt dat verspreide bewijs samen in drie gekoppelde registers die je in een spreadsheet kunt overnemen. Hij is gemaakt voor de wijzigingen in legacy API’s en apps uit de aankondiging van HubSpot van september 2026, en niet als algemene audit van een CRM-implementatie.
Wat moet een audit van legacy HubSpot-integraties omvatten?
Een volledige audit beslaat vijf gebieden: een inventaris van accounts en apps, waargenomen API-activiteit, onderzoek van broncode en automatiseringen, bedrijfsafhankelijkheden en gereedheid voor migratie. Elke bevinding heeft een eigenaar en bewijs nodig. Recent verkeer alleen is niet genoeg, want slapende, seizoensgebonden, reserve- of extern beheerde integraties verschijnen misschien niet in een korte rapportageperiode.
Loop deze snelle scan door voordat je aan het gedetailleerde onderzoek begint:
Maak een lijst van alle HubSpot-accounts binnen de scope: productie, sandbox, test en developer.
Exporteer of noteer elke public app, private app, Service Key en gekoppelde app.
Leg recente API-activiteit en foutlogs vast uit HubSpot en uit elk middlewareplatform.
Doorzoek repositories en automatiseringstools op
/v1/,/v2/,/v3/,/v4/, HubSpot SDK-clients, portal-ID’s, app-ID’s en namen van secrets.Noteer elke webhook, UI-extensie, app-pagina, custom workflowactie en geplande job.
Koppel elke API-call aan de integratie die hem verstuurt en aan het bedrijfsproces dat hij ondersteunt.
Noteer het type credential, de scopes, de opslaglocatie, wie verantwoordelijk is voor rotatie en het bewijs van laatste gebruik.
Vergelijk elke legacy call met de ondersteunde vervanging, inclusief identifiers, payloads, responses en associaties.
Leg per bedrijfskritische integratie vast welk bewijs voor acceptatie nodig is en hoe je tijdelijk doorwerkt.
Wijs een zakelijke eigenaar, een technische eigenaar, een beslissing en een volgende reviewdatum toe.
De checklist is af als elk gevonden onderdeel in een register staat en elke rij genoeg bewijs heeft voor een beslissing: migreren, vervangen, samenvoegen, uitfaseren of verder onderzoeken.
Hoe bepaal je de scope van de audit?
Begin bij accounts, omgevingen en systemen, niet bij endpoints. Zo voorkom je dat een review van alleen productie testportals, developer-accounts, middleware, gearchiveerde repositories of regionale integraties mist. De scope beschrijft welke HubSpot-accounts, externe systemen, leveranciers en codelocaties het team heeft gecontroleerd.
Checklist voor accounts en omgevingen
Noteer de Hub ID, accountnaam, regio, abonnement en het type omgeving.
Stel per account vast wie Super Admin-rechten of toegang tot Developer Tools heeft.
Maak een lijst van productie-, sandbox-, test-, developer- en opgeheven accounts die nog apps of credentials kunnen bevatten.
Noteer externe systemen die data uitwisselen met HubSpot, zoals eCommerce-platforms, ERP, datawarehouses, BI-tools, serviceplatforms, advertentietools en interne applicaties.
Maak een lijst van middleware- en automatiseringsplatforms zoals Workato, Make, Zapier, MuleSoft, n8n, cloud functions en geplande workers.
Breng externe bureaus, app-leveranciers en voormalige partners in kaart die nu of vroeger toegang hadden.
Bepaal de periode waarover je runtime-logs bekijkt en noteer wat buiten die periode kan vallen.
De migratiehandleiding van HubSpot verwijst naar informatie binnen je account, maar een accountoverzicht bewijst niet dat je code buiten HubSpot hebt nagelopen. Bewaar een geschreven scopebeschrijving bij de inventaris, zodat reviewers weten welke onderdelen zijn gecontroleerd en welke nog onbekend zijn.
Deze scope helpt ook om de migratie van integraties los te zien van breder databeheer in HubSpot. Datakwaliteit kan het testbewijs beïnvloeden, maar deze audit richt zich op de code, apps, credentials en workflows die door de platformovergang worden geraakt.
Welke apps en credentials moet je inventariseren?
Inventariseer elke public app, private app, Service Key, OAuth-installatie en app op basis van Projects voordat je een vervanging kiest. Het type app en het type credential beantwoorden verschillende vragen. Een private integratie die alleen data uitwisselt, kan passen bij een Service Key. Webhooks, UI-extensies, app-pagina’s of distributie over meerdere accounts vragen om een route via Projects.
Checklist voor app-architectuur
Noteer de naam van de app, het app-ID, hoe de app is gemaakt en of HubSpot hem als legacy markeert.
Deel hem in als public, private, Marketplace, allowlisted, intern of op basis van Projects.
Noteer elk HubSpot-account waarin de app is geïnstalleerd.
Stel vast of hij webhooks, UI-extensies, app cards, app-pagina’s, serverless functions of custom workflowacties gebruikt.
Bepaal de repository, de projectbestanden, het deploymentproces en de persoon of leverancier die wijzigingen kan uitrollen.
Noteer voor Marketplace-apps de eisen voor listing en certificering los van de eisen voor de API-versie.
Leg migratieadvies dat specifiek voor de app geldt vast, net als functies waarvoor nog geen gelijkwaardige vervanging bestaat.
Het huidige HubSpot Developer Platform maakt en deployt apps via projects en de HubSpot CLI. Voor een app-audit moet je dus weten wie de broncode en de deployment beheert, niet alleen een screenshot van de accountinstellingen hebben.
Checklist voor credentials
Noteer het type credential: legacy private-app-token, OAuth, statisch auth-token, Service Key, Personal Access Key of een ander gedocumenteerd type sleutel.
Noteer de naam van de credential en de verwijzing naar de secret store, zonder de waarde van het secret in het auditbestand te zetten.
Maak een lijst van de toegekende scopes en vergelijk die met de scopes die echt worden gebruikt.
Noteer welke accounts, systemen, jobs en omgevingen de credential delen.
Leg waar mogelijk vast wanneer de credential is aangemaakt, laatst gebruikt, laatst geroteerd, verloopt of is ingetrokken.
Noem de persoon die verantwoordelijk is voor rotatie en voor intrekken in noodgevallen.
Markeer credentials met onbekende gebruikers of ruime scopes voor nader onderzoek.
De uitleg van HubSpot over Service Keys maakt onderscheid tussen toegang van systeem tot systeem voor alleen data, en app-functionaliteit. Service Keys passen bij geplande datasyncs en interne scripts. Ze bieden geen webhooks, UI-extensies, app-pagina’s of distributie via de Marketplace. Leg de werkelijke functionaliteit vast voordat je voor die route kiest.
Hoe vind je API-calls die runtime-rapporten kunnen missen?
Combineer waargenomen activiteit met statisch onderzoek. Runtime-logs laten calls zien die in de gekozen periode zijn gedaan. Zoeken in code, configuratie en automatiseringen laat calls zien die kúnnen worden gedaan. Door de twee te vergelijken vind je stille code, seizoensgebonden jobs, terugvalroutes, gedeelde credentials en integraties waarvan de logs buiten HubSpot staan.
Checklist voor runtime-bewijs
Exporteer recente API-activiteit uit HubSpot voor elk account binnen de scope.
Leg waar mogelijk de methode, het pad, het tijdstip, de responsstatus, de app of credential en het aanroepende account vast.
Controleer logs van middleware, gateways, serverless functies en applicaties op requests naar HubSpot.
Bekijk de geschiedenis van geplande jobs op maandelijkse, driemaandelijkse, jaarlijkse en campagnegebonden runs.
Noteer rate-limit-responses, authenticatiefouten, retries, dead-letter queues en handmatige herverwerking.
Noteer de begin- en einddatum van elke logbron die je gebruikt.
Checklist voor broncode en automatiseringen
Zoek naar letterlijke paden met
/v1/,/v2/,/v3/en/v4/.Zoek naar
api.hubapi.com, imports van de HubSpot SDK, initialisatie van clients, app-ID’s, portal-ID’s, namen van omgevingsvariabelen en verwijzingen naar secrets.Bekijk code die endpointpaden dynamisch opbouwt in plaats van volledige URL’s op te slaan.
Doorzoek CI/CD-variabelen, instellingen van cloud functions, container-secrets en infrastructuurrepositories.
Bekijk low-code workflows, custom code-acties, notebooks, BI-connectors, spreadsheetscripts en recepten in integratieplatforms.
Controleer gearchiveerde repositories en uitgeschakelde workflows die nog kunnen worden hersteld of opnieuw uitgerold.
Vraag leveranciers om een lijst van afhankelijkheden met versies als de broncode buiten je bereik ligt.
Een ouder endpoint kan ook afhangen van een bepaald type identifier. De migratiehandleiding voor de v1 Lists API van HubSpot maakt onderscheid tussen legacyListId en de huidige listId, en waarschuwt dat de waarden tussen verschillende lijsten kunnen overlappen. Noteer opgeslagen ID’s, de mappinglogica en de systemen die de data verder gebruiken naast het endpoint.
Een review van je bestaande HubSpot-integraties helpt om te bepalen welke bedrijfssystemen je moet doorzoeken. De technische inventaris moet wel precies aangeven welke code of workflow elk systeem koppelt.
Welke technische details horen in het API-register?
Maak één rij in het API-register voor elke afzonderlijke combinatie van methode en pad die een integratie gebruikt. Noteer het datacontract, de identifiers, scopes, de status van de vervanging, het foutgedrag en de testcase. Zet je een hele integratie in één rij, dan verdwijnen wijzigingen per endpoint uit beeld en is de testdekking moeilijk te controleren.
Checklist per API-call
HTTP-methode en volledig padpatroon.
Huidige versie en beoogde versie op basis van datum.
Gebruikt HubSpot-object of gebruikte functionaliteit.
Trigger, planning, volumepatroon en piekperiode.
Requestvelden, queryparameters, filters en paginering.
Responsvelden die verderop in de code worden gebruikt.
Object-ID’s, associatie-ID’s, lijst-ID’s, owner-ID’s of eigen identifiers die elders zijn opgeslagen.
Type authenticatie en benodigde scopes.
Omgang met rate limits, retryregels, idempotentie en bescherming tegen duplicaten.
Verwachte foutresponses en monitoringsignaal.
Voorgesteld vervangend endpoint en gedocumenteerde status van gelijkwaardigheid.
Testcase, verwacht resultaat en locatie van het bewijs.
Markeer een endpoint niet als klaar omdat er een vervangende URL bestaat. Klaar betekent dat je genoeg informatie hebt om het gedrag te vergelijken. Wijzigingen in request en response, paginering, identifiers, associaties, rechten en foutafhandeling kunnen elk het resultaat veranderen, ook als de bedrijfshandeling hetzelfde lijkt.
Hoe koppel je de technische inventaris aan bedrijfsafhankelijkheden?
Koppel elke integratie aan het bedrijfsproces, de systemen, teams, timing en het acceptatiebewijs dat erbij hoort. Zo wordt een inventaris voor developers een planningsdocument. Een technisch klein endpoint kan vroege aandacht verdienen als het leadregistratie, toestemming, klantenservice, orderdata of managementrapportages aanstuurt.
Checklist voor bedrijfsafhankelijkheden
Benoem het bedrijfsproces in gewone taal.
Noteer het bronsysteem, het doelsysteem, de richting en de frequentie van de datastroom.
Bepaal voor elk belangrijk veld of object welk systeem leidend is.
Maak een lijst van de teams die de data aanmaken, gebruiken, goedkeuren of afstemmen.
Noteer de bedrijfskritische periode, de acceptabele vertraging en hoe je tijdelijk doorwerkt.
Leg vast hoe een onderbreking zichtbaar wordt voor het bedrijf.
Noteer de controlemethode, zoals aantallen records, veldvergelijking, controle van associaties, inschrijving in workflows of het vergelijken van rapporten.
Wijs één zakelijke goedkeurder en één technische eigenaar aan.
Link bestaande runbooks, diagrammen, supporttickets en documentatie van leveranciers.
Leg de beslissing vast: migreren, vervangen, samenvoegen, uitfaseren of verder onderzoeken.
De zakelijke eigenaar keurt het verwachte gedrag goed. De technische eigenaar bewijst dat gedrag in een testomgeving. Een geslaagde API-response alleen bevestigt niet dat een contact op de juiste lijst is beland, dat een associatie intact is gebleven of dat een rapport dezelfde data heeft gekregen.
Ligt het eigenaarschap extern, documenteer dan ook de commerciële en operationele afhankelijkheid. Het artikel van Flatline over het kiezen van een HubSpot-partner geeft bredere criteria om de technische integratiekennis van een partner te beoordelen. De inventaris heeft daarnaast nog steeds een interne goedkeurder nodig die het zakelijke resultaat kan vastleggen.
Template voor een HubSpot-integratieaudit om over te nemen
De template heeft drie tabbladen, omdat integraties, API-calls en bedrijfsafhankelijkheden elk een ander detailniveau hebben. Geef elke integratie een vaste Integration ID en gebruik die ID om de tabbladen te koppelen. Kopieer elke kopregel naar een apart tabblad of CSV-bestand.
Tabblad 1: integratieregister
Tabblad 2: register van API-calls
Tabblad 3: register van bedrijfsafhankelijkheden en acceptatie
Gebruik waar mogelijk vaste waarden:
Current Status: Active, Dormant, Seasonal, Disabled, Unknown (actief, slapend, seizoensgebonden, uitgeschakeld, onbekend).
Parity Status: Confirmed, Partial, Unavailable, Unchecked (bevestigd, gedeeltelijk, niet beschikbaar, niet gecontroleerd).
Decision: Migrate, Replace, Consolidate, Retire, Investigate (migreren, vervangen, samenvoegen, uitfaseren, onderzoeken).
Approval Status: Not Ready, Ready for Planning, Ready for Build (niet klaar, klaar voor planning, klaar voor bouw).
Laat één persoon de structuur van het register bewaken, terwijl technische en zakelijke eigenaren het bewijs aanleveren. Zo voorkom je dat teams elk hun eigen naam voor dezelfde integratie verzinnen. Delen meerdere jobs één app of credential, houd dan alleen één Integration ID aan als ze ook dezelfde eigenaar en deployment hebben. Jobs die los worden uitgerold of goedgekeurd, krijgen elk een eigen ID, ook als ze hetzelfde token gebruiken.
Loop open vragen door in een korte werksessie, in plaats van het bestand als passief document te behandelen. Elk onopgelost veld eindigt met een eigenaar, een verzoek om bewijs of een onderzoekstaak. Een lege cel zonder actie is meestal nog steeds leeg als de planning begint.
Zet geen access tokens, client secrets of waarden van Service Keys in het werkblad. Sla alleen de verwijzing naar de secret manager en de verantwoordelijke eigenaar op.
Wanneer is de audit klaar voor de migratieplanning?
Een integratie is klaar voor de migratieplanning als het huidige gedrag, het doelpad, de eigenaren, de afhankelijkheden en het acceptatiebewijs zijn gedocumenteerd. Kan het team niet uitleggen wat de integratie doet of hoe je gelijkwaardig gedrag aantoont, dan is de juiste status Investigate en niet Ready for Planning.
Gebruik deze toets voor elke Integration ID:
Toets | Klaar | Nog wachten |
|---|---|---|
Onderzoek | Runtime- en statische zoekacties zijn afgerond voor de vastgelegde scope | Accounts, repositories, automatiseringen of leveranciers zijn nog niet gecontroleerd |
Technisch contract | Calls, payloads, responses, identifiers, scopes en doelpaden zijn vastgelegd | Gelijkwaardigheid van de vervanging of het gebruik van velden verderop is onbekend |
Bedrijfsafhankelijkheid | Proces, leidend systeem, betrokken teams en acceptabele vertraging zijn afgesproken | De gevolgen voor het bedrijf zijn niet te benoemen |
Eigenaarschap | De zakelijke goedkeurder en de technische eigenaar hebben de verantwoordelijkheid aanvaard | Het eigenaarschap ligt bij een oud-medewerker, een onbekende leverancier of een gedeelde inbox |
Bewijs | Testcase, verwacht resultaat, controle en locatie van het bewijs zijn er | Succes is alleen gedefinieerd als een HTTP 2xx-response |
Continuïteit | Een tijdelijke werkroute of grens voor terugdraaien is waar nodig gedocumenteerd | Een kritische workflow heeft geen afgesproken reactie op een onderbreking |
Een onvolledige rij is geen reden om te gokken. Het is bewijs dat er nog onderzoek te doen is. Houd die onbekenden zichtbaar, zodat schattingen en planningen de echte scope weerspiegelen.
Zijn de registers compleet, dan volgen drie stukken: wat HubSpot verandert en wanneer voor de context, het migratieplan voor volgorde, tests en rollback, en de keuze tussen Service Keys en Projects-based apps voor elke integratie die je moet vervangen.
De belangrijkste punten
Audit accounts, apps, credentials, code, automatiseringsplatforms, API-calls en bedrijfsprocessen als samenhangend bewijs, niet als losse lijstjes.
Combineer runtime-logs met zoeken in broncode en configuratie. Elke methode vindt risico’s die de andere kan missen.
Gebruik één rij per API-methode en pad, en noteer de payload, responsvelden, identifiers, scopes, vervanging en testcase.
Houd drie gekoppelde registers bij voor integraties, API-calls en bedrijfsafhankelijkheden. De
Integration IDverbindt technisch bewijs met operationeel eigenaarschap.Zet een integratie pas in de migratieplanning als het doelpad, de eigenaren, het acceptatiebewijs en de continuïteitsroute duidelijk zijn.
De waarde van deze audit zit in de kwaliteit van de overdracht die hij oplevert. Met een volledige inventaris kan de volgende planningsfase het werk ordenen op gevolgen voor het bedrijf en technische onzekerheid. En reviewers hebben één plek om aannames ter discussie te stellen voordat die aannames in productie belanden.
Gerelateerde artikelen
