Legacy API’s en apps in HubSpot: wat je moet auditen vóór de migratiedeadlines van 2027
Door Robin Laseur
De migratie weg van HubSpots legacy API’s is nu een bedrijfsprogramma met twee lagen. Genummerde API-versies maken plaats voor versies op basis van een datum, en de verouderde app-architectuur moet over naar het huidige model op basis van Projects. Een bruikbare audit dekt de aanroepen in productie, de broncode, het type app, de authenticatie, het eigenaarschap en de bedrijfsprocessen die van elke integratie afhangen.
Die breedte is nodig, want een API-endpoint staat zelden op zichzelf. Het zet misschien een lead van de website in HubSpot, verrijkt een klantrecord, synchroniseert een order, start lifecycle-automatisering of voedt een managementrapport. De technische wijziging gebeurt in de code. De gevolgen merk je bij sales, marketing, service of finance.
De aankondiging van HubSpot van 15 september 2026 geeft tijd om je voor te bereiden, maar de deadlines zijn niet gelijk. API-versie, app-architectuur en authenticatie moet je apart controleren voordat je op één migratieplan kunt vertrouwen.
Wijzigingslog
16 september 2026: Eerste publicatie, gebaseerd op HubSpots aankondiging over ondersteuning van legacy API’s en apps, de melding over v4, de documentatie van het Developer Platform en de uitleg over Service Keys.
Wat verandert er in hoe HubSpot API’s en apps ondersteunt?
HubSpot verplaatst integraties van genummerde API-paden en apps van vóór Projects naar API-versies op datum en het huidige Developer Platform. Voor v1- tot en met v3-API’s en legacy publieke en private apps geldt handhaving vanaf september 2027. Voor v4 ligt de datum waarop de ondersteuning stopt eerder: 30 maart 2027, volgens een aparte aankondiging van HubSpot over v4.
Daardoor ontstaan drie werkstromen die je elk apart moet auditen.
Laag | Wat verandert er | Datum of moment om te volgen | Wat de audit moet vaststellen |
|---|---|---|---|
API-versie | Genummerde paden | V4: 30 maart 2027. V1 tot en met v3: handhaving vanaf september 2027 | Welke endpoints worden aangeroepen, waar die aanroepen staan en of er een ondersteunde vervanger is die functioneel hetzelfde doet |
App-architectuur | Legacy publieke en private apps moeten waar nodig over naar het model op basis van Projects | Handhaving vanaf september 2027 | Type app, bouwmodel, distributie, Marketplace-status en eigenaar van het project |
Authenticatie | Lichte data-integraties kunnen Service Keys gebruiken; gedistribueerde apps of apps met veel functies hebben een andere route nodig | Het aanmaken van nieuwe legacy private apps stopt gefaseerd in september en oktober 2026 | Type credential, scopes, bereik over accounts, gebruik van webhooks, UI-functies, rotatie en intrekkingsproces |
Volgens HubSpot gebruiken publieke apps die vóór 23 juni 2026 zijn gemaakt de architectuur van vóór Projects. Die apps hebben het huidige model op basis van Projects nodig om hun Marketplace-vermelding en certificering te houden. Ook voor legacy private apps geldt een migratieverplichting in september 2027. Het aanmaken van nieuwe legacy private apps stopt volgens planning op 28 september 2026 voor nieuwe accounts en op 26 oktober 2026 voor bestaande accounts.
V4 verdient een eigen regel in het plan. In de melding over v4 noemt HubSpot 30 maart 2027 als datum waarop v4 niet meer wordt ondersteund. Schaar die datum niet onder de latere planning voor v1 tot en met v3.
Ook de term niet ondersteund vraagt om zorgvuldige uitleg. Het betekent niet per se dat alle aanroepen op dezelfde ochtend stoppen. Het betekent dat je voor de integratie niet langer mag rekenen op updates, bugfixes, beveiligingsverbeteringen of stabiliteit. Voor een bedrijfskritisch proces is dat verlies aan zekerheid genoeg reden voor een beheerste migratie.
Volgende stap. Weet je al dat je geraakt kunt worden? Begin dan met het migratieplan voor volgorde, tests en uitrol. Weet je nog niet welke endpoints, apps of workflows van de legacy-opzet afhangen, gebruik dan eerst de auditchecklist voor integraties.
Waarom is een audit van alleen de endpoints onvolledig?
Een repository doorzoeken op /v1/, /v2/, /v3/ en /v4/ is nodig, maar laat slechts een deel van het risico zien. Hetzelfde bedrijfsproces kan ook afhangen van een legacy app, een ongeschikte vervangende credential, een gewijzigde object-ID, een workflow in externe middleware of code die niet meer in de gewone runtime-logs opduikt.
De eerste taak lijkt eenvoudig: oude paden opsporen en de URL aanpassen. De tweede taak is het gedrag rond die aanroep behouden.
Een nieuwer endpoint kan een andere request body verwachten, een ander antwoord teruggeven, andere scopes afdwingen of een ID vervangen die een ander systeem opslaat. De migratiegids voor de v1 Lists API van HubSpot maakt bijvoorbeeld onderscheid tussen legacyListId en de nieuwere listId. HubSpot waarschuwt dat je met de verkeerde ID een andere lijst kunt bijwerken of verwijderen. Dat is een probleem van datamapping, geen zoek-en-vervangklus.
Ook bewijs uit productie heeft grenzen. Een rapport met recente API-aanroepen laat actief verkeer zien, maar mist mogelijk:
een kwartaalexport voor finance die in de rapportageperiode niet draaide;
een noodproces dat alleen bij een storing wordt gebruikt;
een seizoensgebonden campagneworkflow die nu gepauzeerd staat;
een integratie die in handen is van een extern bureau of een oud-medewerker;
broncode die nog uitgerold kan worden, ook al is het huidige productiepad stil.
Je audit heeft dus twee soorten bewijs nodig: waargenomen activiteit en een inventaris van code en configuratie. Elk van beide bronnen op zichzelf kan een belangrijke afhankelijkheid zonder eigenaar laten.
Hier wordt een algemene review van je HubSpot-integraties concreter. De vraag is niet langer welke integraties waarde toevoegen. De vraag is van welke onderdelen je bedrijf afhangt, wie ze kan aanpassen en hoe je aantoont dat de vervanger zich correct gedraagt.
Welke delen van het systeem moet je auditen?
Een volledige audit van legacy integraties in HubSpot dekt vijf samenhangende lagen: API-gebruik, app-architectuur, authenticatie, bedrijfsafhankelijkheden en operationeel eigenaarschap. De uitkomst moet een technisch eigenaar in staat stellen de wijziging in te schatten, en een zakelijk eigenaar genoeg context geven om het belang ervan te wegen.
1. API-gebruik in productie en in de broncode
Begin waar mogelijk met de migratie- of gebruiksoverzichten van HubSpot en doorzoek daarna elke relevante codebase en elk automatiseringsplatform. Leg per aanroep de HTTP-methode vast, het endpoint, de API-versie, de request body, de velden in het antwoord, de scopes, de foutafhandeling, het gedrag bij rate limits en hoe vaak de aanroep plaatsvindt.
Zoek verder dan de repository van de hoofdapplicatie. Veelvoorkomende plekken zijn serverless functies, datapipelines, middleware, workflows in integratieplatforms, geplande scripts, rapportagejobs, formulieren op de website, eigen workflowacties en gearchiveerde repositories die nog uitgerold kunnen worden.
Wijs pas een vervangend endpoint aan als je het gedrag hebt vergeleken. Een v1-aanroep en zijn vervanger op datum kunnen dezelfde handeling uitvoeren en toch verschillen in ID’s, associaties, paginering, filters of teruggegeven eigenschappen.
2. Architectuur van publieke en private apps
Maak een lijst van alle publieke en private apps in HubSpot en deel ze in als legacy of op basis van Projects. Documenteer bij publieke apps of ze via de HubSpot Marketplace worden verspreid, via een allowlist worden geïnstalleerd of via een ander distributiemodel worden gebruikt.
Teams met een Marketplace-app hebben twee aparte compliancevragen: welke API-versies de app aanroept en op welke architectuur hij draait. Endpointpaden bijwerken zet een app van vóór Projects niet over naar de huidige architectuur. Andersom werkt een migratie van de architectuur niet elke API-aanroep in de app bij.
Het overzicht van het Developer Platform van HubSpot legt uit dat apps op het huidige platform worden gemaakt en uitgerold via de HubSpot CLI. Dat verandert wat je van eigenaarschap mag verwachten. Je audit moet vaststellen wie de broncode van het project beheert, wie toegang heeft tot deployment, welke omgevingen er zijn en hoe het releaseproces loopt.
3. Authenticatie en gebruik van credentials
Leg per credential vast welke integratie hem gebruikt, welke scopes hij heeft, welke accounts hij kan bereiken, waar hij is opgeslagen, wanneer hij voor het laatst is geroteerd en wie hem kan intrekken. Op dit punt bepaal je ook of de vervanger een Service Key, een apptoken op basis van Projects of OAuth moet gebruiken.
HubSpot beschrijft Service Keys als credentials op accountniveau voor integraties die alleen data uitwisselen. Een geplande datasynchronisatie of een intern script kan in dat model passen. Een integratie die webhooks, UI-extensies, apppagina’s of distributie over meerdere accounts nodig heeft, vraagt om een app op basis van Projects en, waar relevant, OAuth.
Kies het credentialmodel niet op basis van het huidige token alleen. Kies het op basis van wat de integratie doet en hoe ze wordt verspreid.
4. Bedrijfsprocessen en data-afhankelijkheden
Koppel elk technisch onderdeel aan een bedrijfshandeling. Bruikbare categorieën zijn het binnenhalen van leads, synchronisatie van klanten of bedrijven, order- en productdata, lifecycle-automatisering, serviceprocessen, afhandeling van toestemming, het opbouwen van doelgroepen, attributie en managementrapportage.
Leg per proces vast:
welk systeem leidend is;
de richting en frequentie van de datastroom;
de velden en ID’s die stabiel moeten blijven;
de teams die het resultaat gebruiken;
de aanvaardbare vertraging of uitvalduur;
de manier van controleren na een test of overstap.
Dit overzicht van afhankelijkheden helpt ook bij beter databeheer in HubSpot. Een migratie kan technisch geldige antwoorden opleveren en ondertussen de veldmapping, lijstlidmaatschappen, associatielogica of volgorde van updates veranderen. Bij de zakelijke acceptatie test je daarom de records en workflows die eruit komen, niet alleen de responscode van de API.
5. Eigenaarschap, omgevingen en testbewijs
Een integratie zonder benoemde eigenaar is lastiger te migreren dan een complexe integratie met actuele documentatie. Leg de zakelijk eigenaar vast, de technisch eigenaar, de repository, de leverancier, de manier van uitrollen, de testomgeving, de plek waar gemonitord wordt en de route om terug te draaien.
Bepaal daarna welk bewijs nodig is voor acceptatie. Afhankelijk van het proces kan dat gaan om aantallen records, vergelijking per veld, controle van associaties, inschrijvingen in workflows, detectie van dubbelingen, aflevering van webhooks, aansluiting van rapporten of bevestiging door het team dat de uitkomst gebruikt.
De audit moet het eigenaarschap zichtbaar maken voordat de ontwikkeling begint. Kan niemand het verwachte gedrag goedkeuren, dan kan het technische team niet aantonen dat de migratie het heeft behouden.
Hoe bepaal je de prioriteit van de migratierisico’s?
Geef elke integratie prioriteit op basis van deadline, zakelijke gevolgen, onzekerheid over de vervanger en de omvang van de wijziging. Een eerdere einddatum voor ondersteuning verhoogt de urgentie. Een afhankelijkheid van omzet of klantenservice verhoogt de impact. Ontbrekende gelijkwaardigheid van endpoints of onduidelijk eigenaarschap verhoogt de onzekerheid. Een brede wijziging in het responsmodel vergroot de hoeveelheid testwerk.
Een praktische eerste ronde werkt met vier wachtrijen.
Wachtrij | Typische situatie | Aanpak in de planning |
|---|---|---|
A: kritisch in tijd en voor het bedrijf | Afhankelijk van v4, grote operationele impact of een Marketplace-eis | Wijs eigenaren aan en begin als eerste met het valideren van de vervanger |
B: bedrijfskritisch met bekende vervanger | Duidelijk endpoint op datum of migratiepad naar Projects, maar brede impact op processen | Plan bouw en parallel testen, met zakelijke acceptatiecriteria |
C: technisch afgebakend | Intern proces met weinig impact, duidelijke eigenaar, beperkte hoeveelheid data | Bundel in een gecontroleerde migratiebatch |
D: onzeker of slapend | Geen recent verkeer, onduidelijk eigenaar van de code, ontbrekende documentatie of onduidelijk of de vervanger hetzelfde doet | Onderzoek eerst, voordat je iets inschat of verwijdert |
Wachtrij D zorgt vaak voor de meeste frictie in de planning. Een stille integratie kan achterhaald zijn, seizoensgebonden, of wachten op een specifieke gebeurtenis. Zie het ontbreken van verkeer als een vraag die je moet beantwoorden, niet als bewijs dat je het onderdeel veilig kunt verwijderen.
Houd de prioritering ook los van de bouwinschatting. Een kleine codewijziging kan hoge prioriteit verdienen omdat ze het binnenhalen van leads ondersteunt. Een grotere interne rapportage-integratie kan later aan de beurt komen als het bedrijf een afgesproken tijdelijke route heeft. Inspanning en gevolgen zijn verschillende grootheden.
Wat moeten zakelijke en technische eigenaren na de audit beslissen?
De audit eindigt met besluiten, niet met een langere inventaris. Elke integratie heeft een benoemd doelmodel nodig, verantwoordelijke eigenaren, een prioriteit op basis van bewijs, de openstaande vragen en het volgende controlemoment. Zo ontstaat een heldere grens tussen het begrijpen van het risico en het plannen van de migratie zelf.
Bevestig voor elk onderdeel:
Besluit: migreren, vervangen, samenvoegen of uitfaseren.
Doel: endpoint op datum, app op basis van Projects, Service Key, OAuth of een andere gedocumenteerde route.
Eigenaarschap: één zakelijke goedkeurder en één technisch eigenaar.
Bewijs: wat voor en na de overstap moet overeenkomen.
Afhankelijkheid: welke teams, leveranciers, systemen en releasevensters de timing bepalen.
Open punt: ontbrekende gelijkwaardigheid, onduidelijke documentatie, keuze van de credential of niet-geverifieerd slapend gebruik.
Bedrijven met een uitgebreide HubSpot-omgeving moeten misschien ook beoordelen of hun huidige manier van werken het werk aankan. De gids van Flatline over het kiezen van een HubSpot-partner is een goed startpunt om technische kunde, kennis van integraties en klik te beoordelen. De migratieaudit zelf blijft leveranciersneutraal: bepaal eerst het werk, en pas daarna wie het uitvoert.
Bekijk het plan opnieuw als HubSpot details over vervangers publiceert of een ondersteuningsdatum wijzigt. De data in dit artikel zijn gebaseerd op officiële informatie die op 16 september 2026 beschikbaar was. Bij productie en overstap blijft de nieuwste documentatie van HubSpot leidend.
De belangrijkste punten
De migratie van HubSpot raakt API-versies, app-architectuur en authenticatie. Audit die drie lagen apart voordat je ze samenvoegt in één plan.
Voor v4 stopt de ondersteuning eerder, op 30 maart 2027. Handhaving voor v1 tot en met v3 en voor legacy apps volgt volgens de huidige aankondiging van HubSpot in september 2027.
Gebruiksrapporten uit productie hebben een review van broncode en configuratie ernaast nodig. Slapende, seizoensgebonden, nood- en extern beheerde integraties komen mogelijk niet voor in recent verkeer.
Koppel elk technisch onderdeel aan zijn bedrijfsproces, eigenaar, acceptatiebewijs en terugvalroute. Een geslaagde responscode bewijst niet dat de zakelijke uitkomst intact is gebleven.
Sluit de audit af met een besluit en een doelmodel per integratie. Zo wordt een inventaris een migratiebrief.
Het directe doel is een betrouwbaar overzicht van je HubSpot-omgeving: wat er is, wat het ondersteunt, wie de eigenaar is en welk besluit er als volgende komt. Staat dat overzicht eenmaal vast, dan kunnen teams migreren in een volgorde die is gebaseerd op gevolgen en bewijs, niet alleen op het aantal endpoints.
Gerelateerde artikelen
