HubSpot-Legacy-APIs und -Apps: Was Unternehmen vor den Migrationsfristen 2027 prüfen sollten
Von Robin Laseur
Die Migration weg von HubSpots Legacy-APIs ist jetzt ein Unternehmensprogramm mit zwei Ebenen. Nummerierte API-Versionen werden durch datumsbasierte Versionen ersetzt, und die veraltete App-Architektur muss auf die aktuellen, Projects-basierten Optionen umziehen. Ein brauchbares Audit umfasst Aufrufe im Betrieb, Quellcode, App-Typ, Authentifizierung, Zuständigkeiten und die Geschäftsprozesse, die an jeder Integration hängen.
Dieser Umfang ist nötig, weil ein API-Endpoint selten für sich allein steht. Er überträgt vielleicht einen Lead von der Website in HubSpot, reichert einen Kundendatensatz an, synchronisiert eine Bestellung, löst Lifecycle-Automatisierung aus oder speist einen Managementbericht. Die technische Änderung passiert im Code. Die Folgen zeigen sich in Vertrieb, Marketing, Service oder Finanzen.
HubSpots Ankündigung vom 15. September 2026 verschafft Zeit zur Vorbereitung, aber die Fristen sind nicht identisch. API-Version, App-Architektur und Authentifizierung brauchen getrennte Prüfungen, bevor man sich auf einen einzigen Migrationsplan verlassen kann.
Änderungsprotokoll
16. September 2026: Erstveröffentlichung auf Grundlage von HubSpots Ankündigung zum Support für Legacy-APIs und -Apps, dem Hinweis zu v4, der Dokumentation der Developer Platform und den Erläuterungen zu Service Keys.
Was ändert sich an HubSpots Support für APIs und Apps?
HubSpot verlagert Integrationen von nummerierten API-Pfaden und Apps aus der Zeit vor Projects auf datumsbasierte API-Versionen und die aktuelle Developer Platform. Für APIs von v1 bis v3 sowie für öffentliche und private Legacy-Apps greift die Durchsetzung ab September 2027. Für v4 endet der Support früher, am 30. März 2027, laut einer separaten Ankündigung von HubSpot zu v4.
Daraus ergeben sich drei Arbeitsstränge, die Sie jeweils getrennt prüfen sollten.
Ebene | Was sich ändert | Datum oder Auslöser | Was das Audit klären muss |
|---|---|---|---|
API-Version | Nummerierte Pfade | V4: 30. März 2027. V1 bis v3: Durchsetzung ab September 2027 | Welche Endpoints aufgerufen werden, wo die Aufrufe liegen und ob ein unterstützter Ersatz funktional gleichwertig ist |
App-Architektur | Öffentliche und private Legacy-Apps müssen, wo erforderlich, auf das Projects-basierte Modell umziehen | Durchsetzung ab September 2027 | App-Typ, Entstehungsmodell, Verteilung, Marketplace-Status und Verantwortung für das Projekt |
Authentifizierung | Schlanke Datenintegrationen können Service Keys nutzen; verteilte oder funktionsreiche Apps brauchen einen anderen Weg | Das Anlegen neuer privater Legacy-Apps endet stufenweise im September und Oktober 2026 | Art der Zugangsdaten, Scopes, Reichweite über Accounts, Nutzung von Webhooks, UI-Funktionen, Rotation und Widerrufsprozess |
Laut HubSpot nutzen öffentliche Apps, die vor dem 23. Juni 2026 erstellt wurden, die Architektur aus der Zeit vor Projects. Diese Apps brauchen das aktuelle Projects-basierte Modell, um ihren Marketplace-Eintrag und ihre Zertifizierung zu behalten. Auch für private Legacy-Apps gilt eine Migrationspflicht im September 2027. Das Anlegen neuer privater Legacy-Apps soll am 28. September 2026 für neue Accounts und am 26. Oktober 2026 für bestehende Accounts enden.
V4 braucht eine eigene Zeile im Plan. Im Hinweis zu v4 nennt HubSpot den 30. März 2027 als Datum, ab dem v4 nicht mehr unterstützt wird. Ordnen Sie dieses Datum nicht dem späteren Zeitplan für v1 bis v3 unter.
Auch der Begriff nicht unterstützt will sorgfältig gelesen werden. Er heißt nicht zwingend, dass alle Aufrufe am selben Morgen aufhören. Er heißt, dass Sie für die Integration nicht mehr mit Updates, Fehlerbehebungen, Sicherheitsverbesserungen oder Stabilität rechnen können. Bei einem geschäftskritischen Prozess reicht dieser Verlust an Sicherheit, um eine gesteuerte Migration zu verlangen.
Nächster Schritt. Sie wissen bereits, dass Sie betroffen sein könnten? Dann beginnen Sie mit dem Migrationsplan für Reihenfolge, Tests und Rollout. Wissen Sie noch nicht, welche Endpoints, Apps oder Workflows vom Legacy-Setup abhängen, nutzen Sie zuerst die Audit-Checkliste für Integrationen.
Warum reicht ein Audit der Endpoints allein nicht aus?
Ein Repository nach /v1/, /v2/, /v3/ und /v4/ zu durchsuchen, ist notwendig, zeigt aber nur einen Teil des Risikos. Derselbe Geschäftsprozess kann auch von einer Legacy-App abhängen, von ungeeigneten Ersatz-Zugangsdaten, einer geänderten Objekt-ID, einem Workflow in externer Middleware oder von Code, der in den normalen Laufzeit-Logs nicht mehr auftaucht.
Die erste Aufgabe wirkt einfach: alte Pfade finden und die URL ändern. Die zweite Aufgabe besteht darin, das Verhalten rund um diesen Aufruf zu erhalten.
Ein neuerer Endpoint kann einen anderen Request Body erwarten, eine andere Antwortstruktur liefern, andere Scopes verlangen oder eine ID ersetzen, die ein anderes System speichert. HubSpots Migrationsleitfaden für die v1 Lists API unterscheidet zum Beispiel zwischen legacyListId und der neueren listId. HubSpot warnt, dass die falsche ID dazu führen kann, dass eine andere Liste aktualisiert oder gelöscht wird. Das ist ein Problem des Datenmappings, keine Aufgabe für Suchen und Ersetzen.
Auch Nachweise aus dem laufenden Betrieb haben Grenzen. Ein Bericht über aktuelle API-Aufrufe zeigt aktiven Datenverkehr, erfasst aber womöglich nicht:
einen quartalsweisen Finanzexport, der im Berichtszeitraum nicht lief;
einen Notfallprozess, der nur bei einem Ausfall genutzt wird;
einen saisonalen Kampagnen-Workflow, der gerade pausiert ist;
eine Integration, die bei einer externen Agentur oder einem ehemaligen Mitarbeiter liegt;
Quellcode, der weiterhin ausgerollt werden kann, auch wenn der aktuelle Produktionspfad ruht.
Ihr Audit braucht deshalb zwei Arten von Nachweisen: beobachtete Aktivität und eine Bestandsaufnahme von Code und Konfiguration. Jede Quelle für sich kann eine wichtige Abhängigkeit ohne Verantwortlichen zurücklassen.
Hier wird eine allgemeine Prüfung Ihrer HubSpot-Integrationen konkreter. Die Frage ist nicht mehr, welche Integrationen Mehrwert bringen. Die Frage ist, von welchen Bestandteilen Ihr Unternehmen abhängt, wer sie ändern kann und wie Sie nachweisen, dass sich der Ersatz korrekt verhält.
Welche Teile des Systems sollten Sie prüfen?
Ein vollständiges Audit der Legacy-Integrationen in HubSpot umfasst fünf zusammenhängende Ebenen: API-Nutzung, App-Architektur, Authentifizierung, geschäftliche Abhängigkeiten und betriebliche Zuständigkeit. Das Ergebnis sollte es einer technisch verantwortlichen Person ermöglichen, den Aufwand zu schätzen, und der fachlich verantwortlichen Person genug Kontext geben, um die Bedeutung einzuordnen.
1. API-Nutzung im Betrieb und im Quellcode
Beginnen Sie, wo verfügbar, mit den Migrations- oder Nutzungsansichten von HubSpot und durchsuchen Sie danach jede relevante Codebasis und Automatisierungsplattform. Erfassen Sie HTTP-Methode, Endpoint, API-Version, Request Body, Antwortfelder, Scopes, Fehlerbehandlung, Verhalten bei Rate Limits und Aufrufhäufigkeit.
Suchen Sie über das Repository der Hauptanwendung hinaus. Typische Fundorte sind Serverless Functions, Datenpipelines, Middleware, Workflows in Integrationsplattformen, geplante Skripte, Reporting-Jobs, Formulare auf der Website, eigene Workflow-Aktionen und archivierte Repositories, die noch ausgerollt werden können.
Legen Sie einen Ersatz-Endpoint erst fest, wenn Sie das Verhalten verglichen haben. Ein v1-Aufruf und sein datumsbasierter Ersatz können dieselbe Geschäftsaktion abbilden und sich trotzdem in IDs, Zuordnungen, Paginierung, Filtern oder zurückgegebenen Eigenschaften unterscheiden.
2. Architektur öffentlicher und privater Apps
Listen Sie alle öffentlichen und privaten HubSpot-Apps auf und ordnen Sie jede als Legacy oder Projects-basiert ein. Dokumentieren Sie bei öffentlichen Apps, ob sie über den HubSpot Marketplace verteilt, über eine Allowlist installiert oder über ein anderes Verteilungsmodell genutzt werden.
Teams mit Marketplace-Apps haben zwei getrennte Compliance-Fragen: welche API-Versionen die App aufruft und auf welcher Architektur sie läuft. Wer die Endpoint-Pfade aktualisiert, bringt eine App aus der Zeit vor Projects nicht auf die aktuelle Architektur. Umgekehrt aktualisiert eine Migration der Architektur nicht jeden API-Aufruf in der App.
HubSpots Überblick zur Developer Platform erklärt, dass Apps auf der aktuellen Plattform über die HubSpot CLI erstellt und bereitgestellt werden. Das verändert, was Zuständigkeit bedeutet. Ihr Audit sollte klären, wer den Quellcode des Projekts, den Deployment-Zugang, die Umgebungen und den Release-Prozess kontrolliert.
3. Authentifizierung und Nutzung von Zugangsdaten
Erfassen Sie für alle Zugangsdaten, welche Integration sie nutzt, welche Scopes sie haben, welche Accounts sie erreichen, wo sie gespeichert sind, wann sie zuletzt rotiert wurden und wer sie widerrufen kann. An dieser Stelle legen Sie auch fest, ob der Ersatz einen Service Key, ein Token einer Projects-basierten App oder OAuth verwenden soll.
HubSpot beschreibt Service Keys als Zugangsdaten auf Account-Ebene für reine Datenintegrationen. Eine geplante Datensynchronisierung oder ein internes Skript kann in dieses Modell passen. Eine Integration, die Webhooks, UI-Erweiterungen, App-Seiten oder die Verteilung über mehrere Accounts braucht, erfordert eine Projects-basierte App und, wo relevant, OAuth.
Wählen Sie das Modell für die Zugangsdaten nicht allein anhand des aktuellen Tokens. Wählen Sie es danach, was die Integration tut und wie sie verteilt wird.
4. Geschäftsprozesse und Datenabhängigkeiten
Ordnen Sie jedem technischen Bestandteil eine Geschäftsaktion zu. Sinnvolle Kategorien sind Lead-Erfassung, Synchronisierung von Kunden oder Unternehmen, Bestell- und Produktdaten, Lifecycle-Automatisierung, Serviceprozesse, Umgang mit Einwilligungen, Aufbau von Zielgruppen, Attribution und Managementberichte.
Halten Sie für jeden Prozess fest:
das führende System;
Richtung und Häufigkeit des Datenflusses;
die Felder und IDs, die stabil bleiben müssen;
die Teams, die das Ergebnis nutzen;
die akzeptable Verzögerung oder Ausfallzeit;
die Abgleichmethode nach einem Test oder der Umstellung.
Diese Übersicht der Abhängigkeiten unterstützt auch ein besseres Datenmanagement in HubSpot. Eine Migration kann technisch gültige Antworten liefern und dabei Feldzuordnungen, Listenmitgliedschaften, Zuordnungslogik oder die Reihenfolge von Updates verändern. Die fachliche Abnahme muss deshalb die entstehenden Datensätze und Workflows testen, nicht nur den Statuscode der API.
5. Zuständigkeit, Umgebungen und Testnachweise
Eine Integration ohne benannte verantwortliche Person ist schwerer zu migrieren als eine komplexe Integration mit aktueller Dokumentation. Erfassen Sie fachlich Verantwortliche, technisch Verantwortliche, Repository, Anbieter, Deployment-Methode, Testumgebung, Ort des Monitorings und Rückfallweg.
Legen Sie dann fest, welche Nachweise für die Abnahme nötig sind. Je nach Prozess können das Datensatzzahlen sein, Vergleiche auf Feldebene, Prüfungen von Zuordnungen, Workflow-Anmeldungen, Dublettenerkennung, Zustellung von Webhooks, Abstimmung von Berichten oder die Bestätigung des Teams, das mit dem Ergebnis arbeitet.
Das Audit sollte Zuständigkeiten sichtbar machen, bevor die Entwicklung beginnt. Kann niemand das erwartete Verhalten freigeben, kann das technische Team nicht belegen, dass die Migration es erhalten hat.
Wie priorisieren Sie das Migrationsrisiko?
Priorisieren Sie jede Integration nach Frist, geschäftlichen Folgen, Unsicherheit beim Ersatz und Umfang der Änderung. Ein früheres Support-Ende erhöht die Dringlichkeit. Eine Abhängigkeit von Umsatz oder Kundenservice erhöht die Tragweite. Fehlende Gleichwertigkeit von Endpoints oder unklare Zuständigkeit erhöhen die Unsicherheit. Eine weitreichende Änderung des Antwortmodells vergrößert den Testaufwand.
Ein praktischer erster Durchgang arbeitet mit vier Warteschlangen.
Warteschlange | Typische Situation | Reaktion in der Planung |
|---|---|---|
A: zeitkritisch und geschäftskritisch | Abhängigkeit von v4, hohe betriebliche Tragweite oder Marketplace-Anforderung | Verantwortliche benennen und zuerst mit der Validierung des Ersatzes beginnen |
B: geschäftskritisch mit bekanntem Ersatz | Klarer datumsbasierter Endpoint oder Migrationspfad zu Projects, aber breite Auswirkung auf Prozesse | Umsetzung und Paralleltests mit fachlichen Abnahmekriterien einplanen |
C: technisch überschaubar | Interner Prozess mit geringer Tragweite, klare Zuständigkeit, begrenzte Datenmenge | In einem kontrollierten Migrationspaket bündeln |
D: unklar oder ruhend | Kein aktueller Datenverkehr, unklare Zuständigkeit für den Code, fehlende Dokumentation oder unklare Gleichwertigkeit des Ersatzes | Erst untersuchen, dann schätzen oder löschen |
Warteschlange D sorgt oft für die meiste Reibung in der Planung. Eine ruhige Integration kann veraltet sein, saisonal genutzt werden oder auf ein bestimmtes Ereignis warten. Betrachten Sie fehlenden Datenverkehr als offene Frage, nicht als Beweis, dass sich der Bestandteil gefahrlos entfernen lässt.
Halten Sie die Priorisierung außerdem getrennt von der Aufwandsschätzung. Eine kleine Codeänderung kann hohe Priorität verdienen, weil sie die Lead-Erfassung trägt. Eine größere interne Reporting-Integration kann später drankommen, wenn das Unternehmen einen abgestimmten Übergangsweg hat. Aufwand und Folgen sind unterschiedliche Größen.
Was sollten fachlich und technisch Verantwortliche nach dem Audit entscheiden?
Das Audit sollte mit Entscheidungen enden, nicht mit einer längeren Bestandsliste. Jede Integration braucht ein benanntes Zielmodell, verantwortliche Personen, eine auf Nachweisen beruhende Priorität, offene Fragen und den nächsten Prüfpunkt. So entsteht eine klare Grenze zwischen dem Verständnis des Risikos und der Planung der eigentlichen Migration.
Bestätigen Sie für jeden Eintrag:
Entscheidung: migrieren, ersetzen, zusammenführen oder stilllegen.
Ziel: datumsbasierter Endpoint, Projects-basierte App, Service Key, OAuth oder ein anderer dokumentierter Weg.
Zuständigkeit: eine Person für die fachliche Freigabe und eine technisch verantwortliche Person.
Nachweis: was vor und nach der Umstellung übereinstimmen muss.
Abhängigkeit: welche Teams, Anbieter, Systeme und Release-Fenster den Zeitplan beeinflussen.
Offener Punkt: fehlende Gleichwertigkeit, unklare Dokumentation, Wahl der Zugangsdaten oder nicht geprüfte ruhende Nutzung.
Unternehmen mit einer umfangreichen HubSpot-Landschaft müssen womöglich auch prüfen, ob ihr aktuelles Liefermodell die Arbeit tragen kann. Flatlines Leitfaden zur Wahl eines HubSpot-Partners ist ein guter Ausgangspunkt, um technisches Können, Integrationswissen und Passung zu bewerten. Das Migrationsaudit selbst sollte anbieterneutral bleiben: Definieren Sie die Arbeit, bevor Sie entscheiden, wer sie übernimmt.
Prüfen Sie den Plan erneut, wenn HubSpot Details zu Ersatzlösungen veröffentlicht oder ein Support-Datum ändert. Die Daten in diesem Artikel beruhen auf offiziellen Informationen, die am 16. September 2026 verfügbar waren. Zum Zeitpunkt von Produktion und Umstellung bleibt die aktuelle Dokumentation von HubSpot maßgeblich.
Das Wichtigste in Kürze
HubSpots Migration betrifft API-Versionen, App-Architektur und Authentifizierung. Prüfen Sie die drei Ebenen getrennt, bevor Sie sie in einem Plan zusammenführen.
Für v4 endet der Support früher, am 30. März 2027. Die Durchsetzung für v1 bis v3 und für Legacy-Apps folgt laut aktueller Ankündigung von HubSpot im September 2027.
Nutzungsberichte aus dem Betrieb brauchen eine Prüfung von Quellcode und Konfiguration daneben. Ruhende, saisonale, Notfall- und extern betreute Integrationen tauchen im aktuellen Datenverkehr möglicherweise nicht auf.
Ordnen Sie jedem technischen Bestandteil Geschäftsprozess, verantwortliche Person, Abnahmenachweis und Rückfallweg zu. Ein erfolgreicher Statuscode beweist nicht, dass das geschäftliche Ergebnis unverändert geblieben ist.
Schließen Sie das Audit mit einer Entscheidung und einem Zielmodell pro Integration ab. So wird aus einer Bestandsaufnahme ein Migrations-Briefing.
Das unmittelbare Ziel ist eine verlässliche Übersicht Ihrer HubSpot-Landschaft: was es gibt, was es trägt, wer verantwortlich ist und welche Entscheidung als Nächstes ansteht. Steht diese Übersicht, können Teams in einer Reihenfolge migrieren, die sich nach Folgen und Nachweisen richtet und nicht allein nach der Zahl der Endpoints.
Verwandte Artikel
