Webhooks für Vermietsoftware: Wie Echtzeit-Integrationen Systeme synchron halten

Wer schon einmal eine Integration zwischen zwei Systemen gebaut hat, hat wahrscheinlich Code geschrieben, der ungefähr Folgendes tut: alle fünf Minuten die API aufrufen, die neuesten Aufträge abrufen, sie mit dem bereits vorhandenen Stand vergleichen und herausfinden, was sich geändert hat. Das ist Polling, und es ist der Standardansatz, weil er einfach ist. Er ist aber auch verschwenderisch.

Meistens hat sich nichts geändert. Man stellt die Anfrage, bekommt eine Antwort zurück, die genauso aussieht wie die letzte, und verwirft sie. Wiederholt man das alle fünf Minuten, 288 Mal am Tag, für jedes zu synchronisierende Konto, verbraucht man API-Aufrufe, Datenbankabfragen und Rechenleistung, um fast jedes Mal zu erfahren, dass nichts passiert ist.

Schlimmer noch, Polling ist von Natur aus träge. Fragt man alle fünf Minuten ab, liegt die bestmögliche Verzögerung zwischen einem Ereignis und dem Zeitpunkt, an dem das eigene System davon erfährt, nahe null, im schlechtesten Fall knapp unter fünf Minuten. Fragt man seltener ab, um Ressourcen zu sparen, wächst dieser schlechteste Fall weiter. Effizienz und Unmittelbarkeit gleichzeitig zu erreichen, ist mit Polling nicht möglich, man tauscht immer das eine gegen das andere.

Ein Webhook dreht dieses Verhältnis um. Statt dass das eigene System immer wieder fragt, ob sich etwas geändert hat, meldet sich das Vermietsystem in dem Moment, in dem tatsächlich etwas passiert. Man bezahlt nicht mehr für das Fragen, sondern nur noch für die Momente, die zählen.

Ein Webhook ist eine gewöhnliche HTTP-Anfrage, meist ein POST, die ein System automatisch an ein anderes sendet, sobald ein bestimmtes Ereignis eintritt, statt einer Anfrage, die man selbst schickt, wenn man gerade nachsehen möchte. Man registriert beim gewünschten System eine URL, einen Endpunkt auf dem eigenen Server, und wenn dort ein relevantes Ereignis eintritt, sendet das System eine Anfrage an diese URL mit Informationen darüber, was passiert ist.

Das ist der grundlegende Unterschied zu einem normalen API-Aufruf. Eine gewöhnliche API-Anfrage ist Pull-basiert: Man entscheidet selbst, wann man fragt, und das System antwortet nur, wenn es gefragt wird. Ein Webhook ist Push-basiert: Das System entscheidet, wann es sich meldet, basierend auf seinen eigenen Ereignissen, nicht auf dem eigenen Zeitplan. Die Anfrage entsteht aus einem Ereignis heraus, nicht aus einem Client, der gerade jetzt etwas wissen möchte.

In der Praxis verändert das die Form des Integrationscodes vollständig. Statt einer Schleife, die Daten abruft und vergleicht, schreibt man einen kleinen Handler, der eine Anfrage empfängt, prüft, ob sie tatsächlich vom erwarteten System stammt, und auf das beschriebene Ereignis reagiert. Renttix zum Beispiel stellt im Rahmen seiner Entwickler-API Webhook-Endpunkte bereit, sodass ein Unternehmen eine URL registrieren und benachrichtigt werden kann, statt ständig nachfragen zu müssen.

Die Ineffizienz von Polling wird mit wachsendem Vermietbetrieb schlimmer, nicht besser. Ein einzelnes Depot, das eine Handvoll Aufträge mit einem nachgelagerten Tool synchronisiert, kann sich ein Polling alle paar Minuten leisten, ohne dass jemand die Verschwendung bemerkt. Kommen aber weitere Depots, weitere Integrationen und weitere nachgelagerte Systeme hinzu, die alle über Auftrags- und Zahlungsaktivitäten Bescheid wissen müssen, vervielfacht sich die Zahl der Änderungsprüfungen schnell, die meisten davon weiterhin mit einem Nein beantwortet.

Es gibt auch eine praktische Obergrenze: APIs sind aus gutem Grund ratenbegrenzt, und eine Polling-Strategie, die aggressiv genug ist, um sich nah an Echtzeit anzufühlen, stößt oft an diese Grenzen, bevor sie überhaupt annähernd echtzeitnahe Ergebnisse liefert. Am Ende justiert man die Abfragehäufigkeit als Kompromiss zwischen Serverlast, Ratenlimits und der zulässigen Datenveraltung, und keiner dieser Kompromisse wird mit der Zeit einfacher.

Webhooks umgehen diesen Kompromiss vollständig. Die Menge der empfangenen Benachrichtigungen ist proportional zur Anzahl der tatsächlich eingetretenen Ereignisse, nicht dazu, wie oft man sich zum Nachfragen genötigt fühlt. Eine ruhige Woche erzeugt fast keinen Webhook-Verkehr; eine geschäftige Woche erzeugt genau so viele Benachrichtigungen, wie es Ereignisse gibt, nicht mehr.

Der Wert von Webhooks liegt nicht im Mechanismus selbst, sondern darin, was dadurch praktisch möglich wird. Allgemein gesprochen kann ein Vermietsystem Webhooks nutzen, um ein externes System in dem Moment zu informieren, in dem sich etwas ändert: zum Beispiel wenn sich ein Auftragsstatus weiterentwickelt, eine Zahlung eingezogen wird oder eine Rückgabe als abgeschlossen markiert wird. Für denjenigen, der die Integration baut, zählt, dass die Benachrichtigung nahe am tatsächlichen Zeitpunkt des Ereignisses eintrifft, statt erst nach einem möglicherweise langen Abfrageintervall.

Als anschauliches Beispiel: Man stelle sich ein Vermietunternehmen vor, das ein eigenes internes Dashboard für sein Betriebsteam gebaut hat, eine Großbildanzeige dessen, was gerade vermietet ist, was zurückerwartet wird und was bezahlt wurde. Ohne Webhooks bedeutet die Aktualität dieses Dashboards, die API alle paar Minuten zu bombardieren, meist ohne neues Ergebnis. Mit Webhooks lauscht das Backend des Dashboards einfach auf die relevanten Ereignisse und aktualisiert den betroffenen Datensatz in dem Moment, in dem eine Benachrichtigung eintrifft. Der Bildschirm bleibt korrekt, ohne ständiges Nachfragen.

Dasselbe Muster gilt für fast jedes nachgelagerte System, das eine Anbindung wert ist: ein Finanztool, das wissen muss, wann eine Zahlung eingeht, eine Support-Plattform, die einen Auftrag markieren möchte, sobald sich etwas daran ändert, oder eine eigene Reporting-Pipeline, die lieber informiert wird, als selbst nachsehen zu müssen. Welche konkreten Ereignisse eine bestimmte Vermietplattform bereitstellt, variiert, entscheidend ist hier die Struktur der Integration, nicht eine feste Liste von Ereignistypen.

Webhooks bringen einen neuen Fehlermodus mit sich, den Polling nicht kennt: Die Benachrichtigung kann ausbleiben, und keine der beiden Seiten bemerkt das notwendigerweise sofort. Der eigene Endpunkt könnte während eines Deployments für eine Minute nicht erreichbar sein. Eine Netzwerkstörung könnte eine Anfrage verlieren. Der eigene Code könnte mitten in der Verarbeitung einer Nutzlast einen Fehler werfen. Kann man davon nichts sehen, bleibt nur blindes Debuggen übrig, das Raten, ob das Vermietsystem überhaupt versucht hat, sich zu melden, und das Raten, was es gesendet hat.

Genau hier zahlen sich Zustellprotokolle aus. Ein Protokoll der Webhook-Zustellungen zeigt einem Entwickler im Nachhinein, was tatsächlich gesendet wurde und ob es empfangen wurde, statt sich auf Rückschlüsse aus nachgelagerten Symptomen wie einem Dashboard zu verlassen, das still aufgehört hat, sich zu aktualisieren. Die Entwickler-API von Renttix enthält genau aus diesem Grund Zustellprotokolle: Wenn sich eine Integration falsch verhält, lautet die erste sinnvolle Frage fast immer, ob der Webhook gesendet wurde und was er enthielt, und ein Zustellprotokoll beantwortet das direkt, statt die Situation aus den eigenen Anwendungsprotokollen rekonstruieren zu müssen.

Aus demselben Grund ist Anfrageprotokollierung auf der API-Aufrufseite einer Integration wichtig, nicht nur auf der Webhook-Seite. Zwischen Zustellprotokollen für ausgehende Benachrichtigungen und Anfrageprotokollierung für eingehende API-Aufrufe hat ein Entwickler, der auf der API von Renttix aufbaut, Einblick in beide Richtungen der Integration, statt nur die eigene Hälfte davon zu sehen.

Webhooks übernehmen den Teil einer Integration, der sagt, meldet euch, wenn etwas passiert, aber die meisten echten Integrationen müssen die API auch direkt aufrufen, um zusätzliche Details abzurufen, etwas nachzuschlagen oder Daten zurückzuschreiben. Das erfordert einen API-Schlüssel, und API-Schlüssel verdienen dieselbe Sorgfalt wie das Webhook-Design darum herum.

Die Einschränkung des Geltungsbereichs ist wichtig, weil eine Integration nur das tun können sollte, was sie tatsächlich braucht. Ein Schlüssel, der für eine reine Lese-Integration im Reporting erstellt wurde, sollte nicht auch Aufträge ändern können; ein Schlüssel, den ein Finanztool nutzt, das nur Zahlungsdaten benötigt, sollte keinen Zugriff auf den Rest des Kontos haben. Eingeschränkte Schlüssel bedeuten, dass der Schaden bei einer kompromittierten Integration auf das begrenzt bleibt, was genau dieser Schlüssel berühren durfte, nicht auf das gesamte Konto.

Widerrufbarkeit zählt in dem Moment, in dem etwas schiefgeht, oder einfach dann, wenn eine Integration abgeschaltet wird. Ein Schlüssel, der sich sofort widerrufen lässt, ohne den Zugriff einer anderen Integration zu berühren, bedeutet, dass ein kompromittierter oder veralteter Schlüssel in dem Moment aufhört zu funktionieren, in dem man es entscheidet, statt als dauerhaftes Risiko bestehen zu bleiben, weil eine Rotation drei andere Dinge kaputt machen würde. Die Entwickler-API von Renttix stellt aus genau diesem Grund Schlüssel aus, die sowohl eingeschränkt als auch widerrufbar sind, Webhook und Schlüssel sind zwei Hälften desselben sicheren Integrationsdesigns, keine getrennten Themen.

Es gibt ein älteres Muster, das dies ersetzt: Daten regelmäßig aus einem Vermietsystem zu exportieren, eine CSV-Datei, ein geplanter Bericht, ein manueller Download, und dann aus dieser Momentaufnahme neu zu bauen, was man eigentlich brauchte. Das funktioniert, ist aber in dem Moment, in dem es erzeugt wird, immer schon veraltet, und es macht aus jeder Integration ein kleines Data-Engineering-Projekt.

Eine dokumentierte REST-API verändert dieses Verhältnis. Renttix stellt eine dokumentierte REST-API unter /api/v1 bereit, das bedeutet, eine Integration wird gegen eine stabile, beschriebene Schnittstelle gebaut, statt gegen die zufällige Form, die ein einmaliger Export gerade hat. Kombiniert mit Webhooks für Echtzeitbenachrichtigung sowie Zustellprotokollen und Anfrageprotokollierung für Einblick in beide Verkehrsrichtungen, sind die Bausteine vorhanden, um etwas zu bauen, das eher einer lebendigen Verbindung zwischen Systemen ähnelt als einem periodischen Datenabwurf.

Nichts davon erfordert einen großen Entwicklungsaufwand, um Nutzen daraus zu ziehen. Ein einzelner Webhook-Endpunkt, der auf einen Ereignistyp reagiert, abgesichert durch einen eingeschränkten Schlüssel, der nur das kann, was diese Integration braucht, ist bereits eine deutlich bessere Ausgangslage als eine Polling-Schleife oder ein nächtlicher Export, und es ist ein Muster, das man Integration für Integration erweitern kann, wenn der Bedarf wächst.

Der praktische Ausgangspunkt ist klein: Man wählt die eine Information aus, die ein nachgelagertes System wirklich in Echtzeit wissen muss, registriert dafür einen Webhook-Endpunkt und erzeugt einen API-Schlüssel, der auf genau das beschränkt ist, was diese Integration berührt. Während des Testens beobachtet man die Zustellprotokolle, um zu sehen, was tatsächlich gesendet wird, statt es zu erraten.

Von dort aus wächst das Muster natürlich weiter, mehr Ereignisse, mehr Integrationen, jede mit ihrem eigenen eingeschränkten Schlüssel, ohne jemals zu einer Schleife zurückzukehren, die alle paar Minuten dieselbe Frage stellt. Wer abwägen möchte, wie Webhooks und die API in die eigene Umgebung passen würden, kann sich an das Team wenden, um zu besprechen, was angebunden werden soll.