Custom Cards in HubSpot anlegen: Anleitung mit Praxisbeispiel

Was sind Custom Cards, und wo stößt das Standard-CRM an Grenzen?

Eine Custom Card ist ein eigener UI-Baustein auf einer HubSpot-Objektseite, der Daten oder Aktionen zeigt, die es als Standard-Card so nicht gibt. HubSpot liefert für Kontakte, Firmen, Deals und Tickets bereits umfangreiche Standard-Cards mit, Eigenschaften, Aktivitäten, Assoziationen. Bei Custom Objects sieht das anders aus. Sobald ein eigenes Objekt wie „Auftrag“, „Standort“ oder „Vertrag“ im Account angelegt ist, bekommt die Record-Seite zwar eine Eigenschaften-Card und eine allgemeine Assoziations-Übersicht, aber keine spezialisierte Darstellung für Daten, die eigentlich zu einem Standardobjekt gehören.

Line Items sind ein typisches Beispiel dafür. Sie sind technisch fest mit Deals und Angeboten verdrahtet, lassen sich aber über eine eigene Assoziation auch mit jedem Custom Object verknüpfen. Die Assoziation funktioniert, die Anzeige nicht. HubSpot rendert auf einer Custom-Object-Seite keine automatische Line-Item-Tabelle, selbst wenn die verknüpften Datensätze vorhanden sind. Genau diese Lücke schließt eine Custom Card: Sie holt sich die assoziierten Daten aktiv per API und stellt sie so dar, wie es für den jeweiligen Anwendungsfall sinnvoll ist.

Custom Card anlegen: UI Extensions statt Legacy CRM Card API

Für Custom Cards gab es lange zwei Wege. Der ältere ist die CRM Card API: HubSpot ruft bei jedem Seitenaufruf einen extern gehosteten Webhook auf, der JSON mit den anzuzeigenden Daten zurückgibt. Das funktioniert, bedeutet aber einen eigenen Server, eigenes Hosting, eigene Uptime-Verantwortung und eine zusätzliche Latenz bei jedem Seitenaufruf. Der zweite und inzwischen empfohlene Weg sind UI Extensions innerhalb eines Developer Project. Dabei läuft eine React-Komponente nativ in der HubSpot-Oberfläche, ausgeliefert über eine App, ohne dass man selbst einen Endpunkt betreiben muss, der ständig erreichbar sein muss.

Der Unterschied ist nicht nur technischer Komfort. HubSpot baut ältere REST-Schnittstellen konsequent zurück. Alte APIs und Legacy Apps verlieren bis September 2027 ihren Support. Wer heute noch eine Card auf Basis der alten CRM Card API und veralteter Endpunkte aufsetzt, baut sich eine Migration für die nahe Zukunft ein. Neue Cards gehören deshalb grundsätzlich in ein aktuelles Developer Project mit UI Extensions, auch wenn der Einstieg zunächst etwas mehr Tooling verlangt.

Schritt für Schritt: Von der ersten Card zum Deploy

Der Ablauf für eine eigene Custom Card läuft in der Praxis immer ähnlich ab:

• HubSpot CLI installieren und mit dem Account verbinden, dann ein neues Developer Project anlegen. Das Projekt bringt bereits die Ordnerstruktur für Extensions mit.
• Im Extensions-Ordner eine Konfigurationsdatei für die Card anlegen: Typ (CRM Card), Zielort auf der Record-Seite und der oder die Objekttypen, auf denen die Card erscheinen soll, beim Custom Object über dessen Objekttyp-ID.
• Die eigentliche Card als React-Komponente bauen, mit den Bausteinen aus dem HubSpot UI-Extensions-Paket (Tabellen, Text, Trennlinien, Buttons), statt eigenes HTML/CSS zu schreiben.
• Datenzugriff über eine serverless function im selben Projekt lösen: Sie ruft mit dem OAuth-Token der App die CRM API auf, holt zuerst die Assoziationen des aktuellen Records und lädt dann die Eigenschaften der verknüpften Datensätze nach.
• Lokal mit dem Entwicklungsmodus der CLI testen. Die Card lässt sich dabei live im echten CRM-Account vorschauen, ohne einen Zwischenschritt über eine Staging-Umgebung.
• Projekt hochladen und veröffentlichen, Card in den Account-Einstellungen der jeweiligen Objektseite zuweisen. Nutzer können sie danach wie jede andere Card in der Sidebar an- oder abwählen.

Der größte Zeitaufwand liegt meist nicht im UI-Code, sondern in der Frage, welche Felder und Assoziationen tatsächlich gebraucht werden. Das lohnt sich vor dem ersten Zeilencode zu klären, nicht währenddessen.

Praxisbeispiel: Standard Line Items auf einem Custom Object sichtbar machen

In einem konkreten Projekt gab es ein Custom Object für Aufträge, das produktionsrelevante Positionen abbildet, unter anderem mit einer kundenspezifischen Eigenschaft für das verwendete Material. Die Line Items dazu lagen bereits sauber assoziiert vor, waren auf der Auftrags-Seite selbst aber nicht sichtbar, weil HubSpot für Custom Objects eben keine automatische Line-Item-Ansicht mitliefert. Ohne eigene Card hätte jeder im Team für die Positionsdetails erst zum verknüpften Deal wechseln müssen.

Die gebaute Card holt bei jedem Seitenaufruf die mit dem aktuellen Auftrag verknüpften Line Items und stellt sie in einer Tabelle mit den Spalten Position, Werkstoff, Menge, Einzelpreis, Intervall und Gesamtbetrag (netto) dar. Darunter summiert die Card automatisch den Nettobetrag, rechnet die Mehrwertsteuer dazu und zeigt den Bruttobetrag als Endsumme. Für wiederkehrende Positionen gibt die Intervall-Spalte an, in welchem Rhythmus abgerechnet wird, bei einmaligen Positionen bleibt sie leer.

Der praktische Effekt: Wer mit dem Auftrag arbeitet, sieht Preise und Positionen ohne Systemwechsel direkt am Objekt, für das sie relevant sind. Das ist genau die Art von Detail, die eine konsolidierte Datenansicht im CRM in der Praxis ausmacht, nicht ein einzelnes großes Dashboard, sondern viele kleine, punktgenaue Ansichten an der Stelle, wo Teams tatsächlich arbeiten. Technisch steckt dahinter nichts Exotisches: Assoziationsabfrage, Eigenschaftsabruf der verknüpften Line Items über die aktuelle CRM API, serverseitige Berechnung der Summen, Ausgabe als Tabelle. Der Aufwand liegt in der sauberen Fehlerbehandlung, wenn einmal keine Line Items verknüpft sind oder ein Pflichtfeld fehlt.

Häufig gestellte Fragen

Brauche ich für eine Custom Card einen eigenen Server?

Nur bei der alten CRM Card API. Mit UI Extensions läuft die Komponente direkt in der HubSpot-Oberfläche, für Datenzugriffe reicht eine serverless function innerhalb desselben Developer Project.

Kann eine Custom Card mehrere Objekttypen gleichzeitig bedienen?

Ja. Eine Card lässt sich für mehrere Objekttypen konfigurieren und kann auch auf Assoziationsdaten mehrerer verknüpfter Objekte zugreifen, solange die jeweilige Assoziation im Account existiert.

Aktualisieren sich die angezeigten Daten automatisch?

Nein, ohne eigene Logik dafür nicht. Die Card lädt ihre Daten bei jedem Seitenaufruf neu über die API. Bei vielen gleichzeitigen Nutzern lohnt sich ein Blick auf die API-Rate-Limits des Accounts.

Ist die alte CRM Card API für neue Projekte noch sinnvoll?

Technisch lässt sie sich weiter nutzen, wegen der angekündigten Abschaltung alter APIs bis September 2027 ist sie für neue Cards aber keine gute Grundlage mehr. Neue Vorhaben gehören in ein Developer Project mit UI Extensions.