Checkliste für das Audit von Legacy-Integrationen in HubSpot: jeden API-Call, jede App und jede Geschäftsabhängigkeit finden
Von Robin Laseur
Eine Checkliste für ein HubSpot-API-Audit sollte mehr liefern als eine Liste veralteter Endpunkte. Sie muss jeden API-Call mit App-Architektur, Credential, Quellcode, Verantwortlichem, Geschäftsprozess, Stand der Ablösung und Testnachweis verknüpfen. Das Ergebnis ist ein migrationsreifes Inventar, das technische und fachliche Teams gemeinsam prüfen können.
Die Umstellung, die HubSpot 2027 vollzieht, lässt den meisten Unternehmen Zeit für die Migration. Sie legt aber auch ein bekanntes Problem offen: Die wichtigsten Integrationen sind nicht immer die am besten dokumentierten. Ein Token kann in einer Middleware liegen. Ein geplanter Job läuft vielleicht nur einmal im Quartal. Ein einzelner Endpunkt kann unbemerkt Lead-Routing, Reporting oder Bestellsynchronisation tragen.
Diese Checkliste bündelt die verstreuten Nachweise in drei verknüpften Registern, die Sie in eine Tabelle übernehmen können. Sie ist auf die Änderungen an Legacy-APIs und -Apps aus der Ankündigung von HubSpot vom September 2026 zugeschnitten und nicht als allgemeines Audit einer CRM-Implementierung gedacht.
Was sollte ein Audit der Legacy-Integrationen in HubSpot abdecken?
Ein vollständiges Audit umfasst fünf Bereiche: das Inventar von Accounts und Apps, beobachtete API-Aktivität, die Suche in Quellcode und Automatisierungen, geschäftliche Abhängigkeiten und die Bereitschaft für die Migration. Jeder Befund braucht einen Verantwortlichen und einen Nachweis. Aktueller Traffic allein reicht nicht, denn ruhende, saisonale, als Fallback genutzte oder extern verwaltete Integrationen tauchen in einem kurzen Berichtszeitraum womöglich gar nicht auf.
Gehen Sie diesen Schnellcheck durch, bevor Sie mit der detaillierten Bestandsaufnahme beginnen:
Listen Sie alle HubSpot-Accounts im Scope auf: Produktion, Sandbox, Test und Developer.
Exportieren oder erfassen Sie jede Public App, Private App, jeden Service Key und jede verbundene App.
Sichern Sie aktuelle API-Aktivität und Fehlerlogs aus HubSpot und aus jeder Middleware-Plattform.
Durchsuchen Sie Repositories und Automatisierungstools nach
/v1/,/v2/,/v3/,/v4/, HubSpot-SDK-Clients, Portal-IDs, App-IDs und Namen von Secrets.Erfassen Sie jeden Webhook, jede UI-Extension, App-Seite, Custom-Workflow-Aktion und jeden geplanten Job.
Ordnen Sie jeden API-Call der Integration zu, die ihn sendet, und dem Geschäftsprozess, den er unterstützt.
Erfassen Sie Credential-Typ, Scopes, Speicherort, Verantwortlichen für die Rotation und den Nachweis der letzten Nutzung.
Vergleichen Sie jeden Legacy-Call mit der unterstützten Ablösung, einschließlich Identifiern, Payloads, Responses und Assoziationen.
Legen Sie für jede geschäftskritische Integration fest, welcher Abnahmenachweis nötig ist und wie der Betrieb übergangsweise weiterläuft.
Bestimmen Sie einen fachlichen Verantwortlichen, einen technischen Verantwortlichen, eine Entscheidung und den nächsten Prüftermin.
Die Checkliste ist vollständig, wenn jedes gefundene Element in einem Register steht und jede Zeile genug Nachweise für eine Entscheidung enthält: migrieren, ersetzen, zusammenführen, stilllegen oder weiter untersuchen.
Wie legen Sie den Scope des Audits fest?
Beginnen Sie bei Accounts, Umgebungen und Systemen, nicht bei Endpunkten. So verhindern Sie, dass eine Prüfung, die sich nur auf die Produktion beschränkt, Testportale, Developer-Accounts, Middleware, archivierte Repositories oder regionale Integrationen übersieht. Der Scope hält fest, welche HubSpot-Accounts, externen Systeme, Dienstleister und Code-Speicherorte das Team geprüft hat.
Checkliste für Accounts und Umgebungen
Erfassen Sie Hub-ID, Accountname, Region, Abonnement und Art der Umgebung.
Ermitteln Sie für jeden Account, wer Super-Admin-Rechte oder Zugriff auf die Developer Tools hat.
Listen Sie Produktions-, Sandbox-, Test-, Developer- und stillgelegte Accounts auf, die noch Apps oder Credentials enthalten können.
Erfassen Sie externe Systeme, die Daten mit HubSpot austauschen, etwa E-Commerce-Plattformen, ERP, Data Warehouses, BI-Tools, Serviceplattformen, Werbetools und interne Anwendungen.
Listen Sie Middleware- und Automatisierungsplattformen auf, etwa Workato, Make, Zapier, MuleSoft, n8n, Cloud Functions und geplante Worker.
Ermitteln Sie externe Agenturen, App-Anbieter und frühere Umsetzungspartner, die aktuell oder früher Zugriff hatten.
Legen Sie den Zeitraum fest, über den Sie Runtime-Logs auswerten, und notieren Sie, was dieser Zeitraum möglicherweise nicht abdeckt.
Die Migrationshinweise von HubSpot verweisen auf Informationen innerhalb des Accounts. Eine Accountansicht beweist aber nicht, dass Sie Code außerhalb von HubSpot geprüft haben. Bewahren Sie eine schriftliche Scope-Beschreibung beim Inventar auf, damit Prüfer wissen, welche Bereiche kontrolliert wurden und welche noch unbekannt sind.
Der Scope hilft auch, die Migration der Integrationen vom umfassenderen Datenmanagement in HubSpot zu trennen. Die Datenqualität kann die Testnachweise beeinflussen, doch dieses Audit konzentriert sich auf Code, Apps, Credentials und Workflows, die von der Plattformumstellung betroffen sind.
Welche Apps und Credentials müssen erfasst werden?
Erfassen Sie jede Public App, Private App, jeden Service Key, jede OAuth-Installation und jede Projects-basierte App, bevor Sie eine Ablösung wählen. App-Typ und Credential-Typ beantworten unterschiedliche Fragen. Eine private Integration, die nur Daten austauscht, kann zu einem Service Key passen. Webhooks, UI-Extensions, App-Seiten oder die Verteilung über mehrere Accounts erfordern dagegen einen Weg über Projects.
Checkliste zur App-Architektur
Erfassen Sie App-Name, App-ID, Erstellungsmodell und ob HubSpot die App als Legacy kennzeichnet.
Ordnen Sie sie ein als Public, Private, Marketplace, Allowlisted, intern oder Projects-basiert.
Erfassen Sie jeden HubSpot-Account, in dem die App installiert ist.
Klären Sie, ob sie Webhooks, UI-Extensions, App Cards, App-Seiten, Serverless Functions oder Custom-Workflow-Aktionen nutzt.
Ermitteln Sie Repository, Projektdateien, Deployment-Prozess und die Person oder den Anbieter, der Änderungen ausrollen kann.
Erfassen Sie bei Marketplace-Apps die Anforderungen an Listing und Zertifizierung getrennt von den Anforderungen an die API-Version.
Halten Sie App-spezifische Migrationshinweise fest, ebenso Funktionen, für die es noch keinen gleichwertigen Ersatz gibt.
Die aktuelle HubSpot Developer Platform erstellt und deployt Apps über Projects und die HubSpot CLI. Ein App-Audit braucht deshalb die Zuständigkeit für Quellcode und Deployment, nicht nur einen Screenshot der Accounteinstellungen.
Checkliste für Credentials
Erfassen Sie den Credential-Typ: Legacy-Private-App-Token, OAuth, statischer Auth-Token, Service Key, Personal Access Key oder ein anderer dokumentierter Schlüsseltyp.
Erfassen Sie den Namen des Credentials und den Verweis auf den Secret Store, ohne den Wert des Secrets in das Audit-Dokument zu schreiben.
Listen Sie die gewährten Scopes auf und vergleichen Sie sie mit den tatsächlich genutzten.
Erfassen Sie Accounts, Systeme, Jobs und Umgebungen, die sich das Credential teilen.
Halten Sie, soweit verfügbar, Nachweise zu Erstellung, letzter Nutzung, letzter Rotation, Ablauf und Widerruf fest.
Benennen Sie die Person, die für Rotation und Notfall-Widerruf zuständig ist.
Markieren Sie Credentials mit unbekannten Nutzern oder weit gefassten Scopes zur genaueren Prüfung.
Die Hinweise von HubSpot zu Service Keys unterscheiden zwischen reinem Datenzugriff von System zu System und App-Funktionalität. Service Keys eignen sich für geplante Datensynchronisationen und interne Skripte. Webhooks, UI-Extensions, App-Seiten oder die Verteilung über den Marketplace bieten sie nicht. Erfassen Sie die tatsächliche Funktionalität, bevor Sie diesen Weg wählen.
Wie finden Sie API-Calls, die Runtime-Berichte übersehen?
Kombinieren Sie beobachtete Aktivität mit statischer Suche. Runtime-Logs zeigen Calls, die im gewählten Zeitraum stattgefunden haben. Die Suche in Code, Konfiguration und Automatisierungen zeigt Calls, die stattfinden könnten. Der Vergleich beider deckt stillen Code, saisonale Jobs, Fallback-Pfade, geteilte Credentials und Integrationen auf, deren Logs außerhalb von HubSpot liegen.
Checkliste für Runtime-Nachweise
Exportieren Sie die aktuelle API-Aktivität aus HubSpot für jeden Account im Scope.
Erfassen Sie, soweit verfügbar, Methode, Pfad, Zeitstempel, Response-Status, App oder Credential und den aufrufenden Account.
Prüfen Sie Logs von Middleware, Gateways, Serverless-Umgebungen und Anwendungen auf Requests an HubSpot.
Prüfen Sie die Historie geplanter Jobs auf monatliche, quartalsweise, jährliche und kampagnenbezogene Läufe.
Erfassen Sie Rate-Limit-Responses, Authentifizierungsfehler, Retries, Dead-Letter-Queues und manuelle Nachverarbeitung.
Notieren Sie Start- und Enddatum jeder genutzten Logquelle.
Checkliste für Quellcode und Automatisierungen
Suchen Sie nach literalen Pfaden mit
/v1/,/v2/,/v3/und/v4/.Suchen Sie nach
api.hubapi.com, Importen des HubSpot SDK, Client-Initialisierungen, App-IDs, Portal-IDs, Namen von Umgebungsvariablen und Verweisen auf Secrets.Prüfen Sie Code, der Endpunktpfade dynamisch zusammensetzt, statt vollständige URLs zu speichern.
Durchsuchen Sie CI/CD-Variablen, Einstellungen von Cloud Functions, Container-Secrets und Infrastruktur-Repositories.
Prüfen Sie Low-Code-Workflows, Custom-Code-Aktionen, Notebooks, BI-Connectoren, Tabellenskripte und Rezepte in Integrationsplattformen.
Prüfen Sie archivierte Repositories und deaktivierte Workflows, die sich noch wiederherstellen oder erneut ausrollen lassen.
Bitten Sie Anbieter um eine versionierte Liste der Abhängigkeiten, wenn der Quellcode nicht in Ihrer Hand liegt.
Ein älterer Endpunkt kann außerdem an eine bestimmte Art von Identifier gebunden sein. Der Migrationsleitfaden für die v1 Lists API von HubSpot unterscheidet zwischen legacyListId und der aktuellen listId und weist darauf hin, dass sich die Werte über verschiedene Listen hinweg überschneiden können. Erfassen Sie gespeicherte IDs, die Mapping-Logik und die nachgelagerten Nutzer neben dem Endpunkt.
Ein Blick auf Ihre bestehenden HubSpot-Integrationen hilft, die zu durchsuchenden Geschäftssysteme zu bestimmen. Das technische Inventar sollte aber genau den Code oder Workflow nennen, der jedes dieser Systeme anbindet.
Welche technischen Angaben gehören ins API-Register?
Legen Sie im API-Register eine Zeile für jede eigenständige Kombination aus Methode und Pfad an, die eine Integration nutzt. Erfassen Sie Datenvertrag, Identifier, Scopes, Stand der Ablösung, Fehlerverhalten und Testfall. Wer eine ganze Integration in einer Zeile zusammenfasst, verdeckt endpunktspezifische Änderungen und erschwert die Prüfung der Testabdeckung.
Checkliste pro API-Call
HTTP-Methode und vollständiges Pfadmuster.
Aktuelle Version und datumsbasierte Zielversion.
Genutztes HubSpot-Objekt oder genutzte Funktion.
Trigger, Zeitplan, Volumenmuster und Spitzenzeit.
Request-Felder, Query-Parameter, Filter und Paginierung.
Response-Felder, die nachgelagerter Code verwendet.
Objekt-IDs, Assoziations-IDs, Listen-IDs, Owner-IDs oder eigene Identifier, die anderswo gespeichert sind.
Authentifizierungsart und benötigte Scopes.
Umgang mit Rate Limits, Retry-Regeln, Idempotenz und Schutz vor Duplikaten.
Erwartete Fehler-Responses und Monitoring-Signal.
Vorgeschlagener Ersatz-Endpunkt und dokumentierter Stand der Gleichwertigkeit.
Testfall, erwartetes Ergebnis und Ablageort des Nachweises.
Markieren Sie einen Endpunkt nicht als bereit, nur weil es eine Ersatz-URL gibt. Bereit heißt, dass genug Informationen vorliegen, um das Verhalten zu vergleichen. Änderungen an Request und Response, Paginierung, Identifiern, Assoziationen, Berechtigungen und Fehlerbehandlung können jeweils das Ergebnis verändern, auch wenn der fachliche Vorgang gleich aussieht.
Wie verknüpfen Sie das technische Inventar mit geschäftlichen Abhängigkeiten?
Ordnen Sie jede Integration dem Geschäftsprozess, den Systemen, Teams, dem Timing und dem Abnahmenachweis zu, die dazugehören. So wird aus einem Entwickler-Inventar ein Planungsdokument. Ein technisch kleiner Endpunkt kann frühe Aufmerksamkeit verdienen, wenn er Lead-Erfassung, Einwilligungen, Kundenservice, Bestelldaten oder das Management-Reporting steuert.
Checkliste für geschäftliche Abhängigkeiten
Benennen Sie den Geschäftsprozess in einfacher Sprache.
Erfassen Sie Quellsystem, Zielsystem, Richtung und Häufigkeit des Datenflusses.
Bestimmen Sie für jedes wichtige Feld und Objekt das führende System.
Listen Sie die Teams auf, die die Daten anlegen, nutzen, freigeben oder abgleichen.
Erfassen Sie den geschäftskritischen Zeitraum, die akzeptable Verzögerung und den Übergangsbetrieb.
Legen Sie fest, woran das Unternehmen eine Unterbrechung erkennt.
Erfassen Sie die Abgleichsmethode, etwa Datensatzzahlen, Feldvergleiche, Prüfung von Assoziationen, Workflow-Aufnahmen oder den Abgleich von Berichten.
Bestimmen Sie eine fachliche Freigabe und einen technischen Verantwortlichen.
Verlinken Sie vorhandene Runbooks, Diagramme, Support-Tickets und Anbieterdokumentation.
Halten Sie die Entscheidung fest: migrieren, ersetzen, zusammenführen, stilllegen oder weiter untersuchen.
Die fachlich verantwortliche Person gibt das erwartete Verhalten frei. Der technische Verantwortliche weist dieses Verhalten in einer Testumgebung nach. Eine erfolgreiche API-Response allein belegt nicht, dass ein Kontakt auf der richtigen Liste gelandet ist, eine Assoziation erhalten blieb oder ein Bericht dieselben Daten bekommen hat.
Liegt die Zuständigkeit extern, dokumentieren Sie auch die kaufmännische und operative Abhängigkeit. Der Beitrag von Flatline zur Wahl eines HubSpot-Partners nennt weitere Kriterien, um die technische Integrationskompetenz eines Partners zu beurteilen. Das Inventar braucht trotzdem eine interne Freigabe, die das fachliche Ergebnis definieren kann.
Vorlage für ein HubSpot-Integrationsaudit zum Kopieren
Die Vorlage hat drei Tabs, weil Integrationen, API-Calls und geschäftliche Abhängigkeiten unterschiedlich detailliert sind. Geben Sie jeder Integration eine feste Integration ID und verknüpfen Sie die Tabs über diese ID. Kopieren Sie jede Kopfzeile in einen eigenen Tab oder eine eigene CSV-Datei.
Tab 1: Integrationsregister
Tab 2: Register der API-Calls
Tab 3: Register für geschäftliche Abhängigkeiten und Abnahme
Verwenden Sie, wo möglich, feste Werte:
Current Status: Active, Dormant, Seasonal, Disabled, Unknown (aktiv, ruhend, saisonal, deaktiviert, unbekannt).
Parity Status: Confirmed, Partial, Unavailable, Unchecked (bestätigt, teilweise, nicht verfügbar, ungeprüft).
Decision: Migrate, Replace, Consolidate, Retire, Investigate (migrieren, ersetzen, zusammenführen, stilllegen, untersuchen).
Approval Status: Not Ready, Ready for Planning, Ready for Build (nicht bereit, bereit für die Planung, bereit für die Umsetzung).
Bestimmen Sie eine Person, die die Struktur des Registers verantwortet, während technische und fachliche Verantwortliche die Nachweise liefern. So vermeiden Sie, dass verschiedene Teams unterschiedliche Namen für dieselbe Integration vergeben. Teilen sich mehrere Jobs eine App oder ein Credential, behalten Sie nur dann eine gemeinsame Integration ID, wenn sie auch dieselbe Zuständigkeit und dasselbe Deployment haben. Jobs, die unabhängig ausgerollt oder freigegeben werden, erhalten eigene IDs, auch wenn sie denselben Token nutzen.
Besprechen Sie offene Fragen in einer kurzen Arbeitssitzung, statt die Tabelle als passives Dokument zu behandeln. Jedes ungeklärte Feld sollte mit einem Verantwortlichen, einer Nachweisanfrage oder einer Prüfaufgabe enden. Eine leere Zelle ohne Maßnahme ist meist immer noch leer, wenn die Planung beginnt.
Legen Sie keine Access Tokens, Client Secrets oder Werte von Service Keys im Arbeitsblatt ab. Speichern Sie nur den Verweis auf den Secret Manager und den zuständigen Verantwortlichen.
Wann ist das Audit bereit für die Migrationsplanung?
Eine Integration ist bereit für die Migrationsplanung, wenn aktuelles Verhalten, Zielpfad, Verantwortliche, Abhängigkeiten und Abnahmenachweise dokumentiert sind. Kann das Team nicht erklären, was die Integration tut oder wie sich gleichwertiges Verhalten nachweisen lässt, lautet der richtige Status Investigate und nicht Ready for Planning.
Nutzen Sie diese Prüfstufen für jede Integration ID:
Prüfstufe | Bereit | Zurückstellen |
|---|---|---|
Bestandsaufnahme | Runtime- und statische Suche sind für den festgelegten Scope abgeschlossen | Accounts, Repositories, Automatisierungen oder Anbieter sind noch ungeprüft |
Technischer Vertrag | Calls, Payloads, Responses, Identifier, Scopes und Zielpfade sind erfasst | Gleichwertigkeit des Ersatzes oder nachgelagerte Feldnutzung ist unbekannt |
Geschäftliche Abhängigkeit | Prozess, führendes System, betroffene Teams und akzeptable Verzögerung sind abgestimmt | Die geschäftlichen Folgen lassen sich nicht benennen |
Zuständigkeit | Fachliche Freigabe und technischer Verantwortlicher haben die Verantwortung übernommen | Die Zuständigkeit liegt bei einem ehemaligen Mitarbeiter, einem unbekannten Anbieter oder einem geteilten Postfach |
Nachweis | Testfall, erwartetes Ergebnis, Abgleich und Ablageort des Nachweises liegen vor | Erfolg ist nur als HTTP-2xx-Response definiert |
Kontinuität | Übergangsbetrieb oder Rollback-Grenze sind, wo nötig, dokumentiert | Für einen kritischen Workflow gibt es keine abgestimmte Reaktion auf eine Unterbrechung |
Eine unvollständige Zeile ist kein Grund zu raten. Sie ist ein Beleg dafür, dass noch Bestandsaufnahme nötig ist. Halten Sie diese Unbekannten sichtbar, damit Schätzungen und Zeitpläne den tatsächlichen Scope abbilden.
Sind die Register vollständig, folgen drei Texte: was HubSpot ändert und wann für den Kontext, der Migrationsplan für Reihenfolge, Tests und Rollback, und die Wahl zwischen Service Keys und Projects-based Apps für jede Integration, die Sie ersetzen müssen.
Das Wichtigste in Kürze
Prüfen Sie Accounts, Apps, Credentials, Code, Automatisierungsplattformen, API-Calls und Geschäftsprozesse als zusammenhängende Nachweise statt als getrennte Listen.
Kombinieren Sie Runtime-Logs mit der Suche in Quellcode und Konfiguration. Jede Methode findet Risiken, die die andere übersehen kann.
Nutzen Sie eine Zeile pro API-Methode und Pfad und erfassen Sie Payload, Response-Felder, Identifier, Scopes, Ablösung und Testfall.
Führen Sie drei verknüpfte Register für Integrationen, API-Calls und geschäftliche Abhängigkeiten. Die
Integration IDverbindet technische Nachweise mit operativer Zuständigkeit.Nehmen Sie eine Integration erst in die Migrationsplanung auf, wenn Zielpfad, Verantwortliche, Abnahmenachweise und Übergangsbetrieb geklärt sind.
Der Wert dieses Audits liegt in der Qualität der Übergabe, die es schafft. Ein vollständiges Inventar erlaubt der nächsten Planungsphase, die Arbeit nach geschäftlichen Folgen und technischer Unsicherheit zu ordnen. Und es gibt Prüfern einen zentralen Ort, um Annahmen zu hinterfragen, bevor diese Annahmen in der Produktion landen.
Verwandte Artikel
