Ein Unified-Webhook-Modell für jedes System, das Sie anbinden
Manche Systeme senden Events. Viele senden gar nichts. Maesn gibt Ihnen einen Webhook zum Abonnieren, eine Nutzlastform zum Verarbeiten und eine Signatur zum Prüfen, und pollt selbst, wo ein System schweigt.
{
"eventType": "CREATED",
"resource": "INVOICE",
"resourceId": "bca91f06…"
}
Was sind Unified Webhooks
Ein Webhook ist der Unterschied zwischen Fragen und Erfahren. Statt eine API nach Zeitplan aufzurufen, um zu sehen, ob sich etwas geändert hat, melden Sie einmal eine URL an, und das System ruft Sie auf, wenn es so weit ist. Für Anbindungen, die Daten im Gleichstand halten, ist das der Unterschied zwischen Minuten Rückstand und wenigen Sekunden, und zwischen dauerndem Verkehr und Verkehr nur bei Neuigkeiten.
Der Haken ist, dass Webhooks der am wenigsten standardisierte Teil jeder API sind. Die Unterstützung ist ungleich, die Nutzlasten widersprechen sich, und das Vokabular für ein angelegtes Objekt wechselt von System zu System. Unified Webhooks fassen das in ein Abo-Modell und einen Event-Rumpf, ausgeliefert über dasselbe normalisierten Datenmodell wie der Rest der Unified API. Sie schreiben einen Handler, und er funktioniert weiter, während Ihre Kunden neue Systeme mitbringen.
Events sind der am wenigsten standardisierte Teil
Jedes System beantwortet dieselben vier Fragen anders, angefangen damit, ob es Ihnen überhaupt etwas sagt. Wer direkt dagegen baut, braucht je Anbindung einen eigenen Listener.
App-basiert oder nutzerbasiert, und das ändert Ihren Code
Wo es Webhooks gibt, haben ERP- und Buchhaltungshersteller sich auf zwei unvereinbare Modelle festgelegt. Welches ein System nutzt, entscheidet, wie viel Verteilung und Trennung Ihnen gehört.
App-basiert
- Alle Events aller verbundenen Nutzer kommen an einem Endpunkt an
- Jede Nutzlast trägt eine Nutzerkennung, nach der Sie verteilen müssen
- Üblich, wo ein Hersteller einen großen App-Marktplatz betreibt
- Legt Verteilung, Prüfung und Nutzertrennung auf Ihre Seite
Nutzerbasiert
- Pro Nutzer und pro Event-Typ wird ein Abo angelegt
- Das Zustellziel ist explizit statt geteilt
- Üblich in ERP- und Mid-Market-Systemen mit strengerer Trennung
- Mehr zu verwalten, klarere Grenzen zwischen Kunden
Bei den Nutzlasten geht es genauso auseinander. Manche Systeme senden ein Ping-and-Pull-Signal: Das Event sagt, welches Objekt sich geändert hat, und Sie holen das Objekt selbst in einem zweiten Aufruf. Andere legen Geschäftsdaten direkt in die Nutzlast, was einen Aufruf spart und das vergrößert, was Sie prüfen müssen. In der Praxis fehlt selbst großzügigen Nutzlasten meist ein Feld, das ein echter Anwendungsfall braucht, der zweite Aufruf passiert also ohnehin.
Maesn standardisiert für jedes Event auf Ping and Pull, nativ oder nicht. Das Event benennt das Objekt, Sie lesen es über die Unified API, und die Nutzlast wird nie zu einem Ort, an dem Kundendaten unterwegs liegen. Das ist ebenso eine bewusste Sicherheitseigenschaft wie eine der Einheitlichkeit, und sie macht einen Handler über beide Herstellermodelle hinweg tragfähig.
Welche Systeme Events pushen, und welche stumm bleiben
Zu ERP- und Buchhaltungssystemen mit eigenen Webhooks und Triggern: Eine Minderheit hat sie, und die Mehrheit wird sie nie haben.
Events kommen über eine dauerhafte Verbindung statt als einzelne HTTP-Anfragen, und die muss je Kunde offen gehalten, neu aufgebaut und skaliert werden. Maesn hält sie und sendet daraus gewöhnliche vereinheitlichte Events.
Unterstützung gibt es, sie folgt aber Xentrals eigenen Konventionen und ist noch in der Beta, die Form kann sich also ohne Ankündigung ändern. Eine Änderung auf ihrer Seite fängt Maesn ab, statt dass Sie sie nachhalten müssen.
Das ist die Mehrheit, und darunter sind die im deutschen Markt gefragtesten Systeme. Deshalb ist „unterstützt System X Webhooks“ die falsche Grundlage für eine Architektur: Die Antwort ist meist nein, und sie ändert sich unangekündigt.
Alle 27 liefern über Maesn vereinheitlichte Events, in einem Modell mit einer Nutzlastform, ob das System nativ pusht oder Maesn es abfragt und das Event selbst sendet.
Die zwei Sonderfälle, Fortnox und Xentral, erreichen Sie wie alles andere als gewöhnliche vereinheitlichte Events. Was jedes System darunter veröffentlicht, und warum eine Einschätzung je Hersteller den Kontakt mit dieser Tabelle nicht übersteht, steht System für System in unserem Artikel zur Webhook-Landschaft.
Einmal abonnieren, ein Event verarbeiten
Ein Endpunkt legt ein Abo für einen Kunden an. Von da an kommen die Events in derselben Form an Ihrer Callback-URL an, aus welchem System sie auch stammen.
Wohin Events gehen
Der Endpunkt auf Ihrer Seite, der jedes Event dieses Abos entgegennimmt, als POST-Request.
Wovon Sie hören
Abonnieren Sie angelegte, geänderte oder gelöschte Objekte, mit einem Vokabular auf jedem System.
Welche Objekte
Die Ressource, die Sie beobachten wollen, etwa eine Rechnung oder einen Kunden, überall gleich benannt.
Ein Webhook-Typ
Ein einziger Unified Webhook deckt jedes System ab, sodass Sie einen Handler schreiben statt einen je Anbindung.
Synthetische Webhooks
Für Systeme, die nativ nichts pushen, fragt Maesn für Sie ab und sendet dasselbe Event, sodass die Lücke Ihren Code nie erreicht.
Abos je Kunde
Jedes Abo gehört zu einem Kunden, sodass seine Events über sein eigenes Abo ankommen und trennbar bleiben.
Signierte Events
Jedes Event trägt eine HMAC-SHA256-Signatur über dem Rohrumpf, sodass Sie seine Herkunft von Maesn belegen können, bevor Sie ihm trauen.
POST /webhooksx-api-key: YOUR_API_KEYx-account-key: CUSTOMER_ACCOUNT_KEY{"callbackUrl": "https://your-app.com/events","eventType": "CREATED","resource": "INVOICE"}
Events aus Systemen, die nichts pushen
Das ist der Teil, den es ohne vereinheitlichende Ebene nicht gibt. Hat ein System keine nativen Webhooks oder deckt nur einen Bruchteil seiner Objekte ab, lautet die übliche Antwort, dass Sie einen Poller bauen: einen Zeitplan, einen Cursor je Kunde und je Ressource, Änderungserkennung und eine Warteschlange, um die Last zu glätten. Es funktioniert, und es wird zu dauerhafter Infrastruktur, die Ihnen für immer gehört.
Maesn betreibt diesen Poller stattdessen und macht aus dem Ergebnis ein normales Event. Sie abonnieren genauso, wie Sie es bei einem nativen Webhook täten, und Sie bekommen denselben Rumpf mit demselben eventType, derselben resource und derselben resourceId. In Ihrem Handler unterscheidet die beiden nichts, und das ist der Punkt: Ob ein System Events pusht, ist keine Eingangsgröße Ihrer Architektur mehr. Das Abfragen dahinter wird von Asynchronous Processing getaktet, es bleibt also innerhalb der Limits jedes Systems, ohne dass Sie darum herum planen. Sie werden sie auch als virtuelle Webhooks bezeichnet sehen; es ist dieselbe Idee unter anderem Namen.
Die Lücke, die sie schließen, sind nicht nur ganze Systeme, es sind Objekte. Native Webhook-Unterstützung ist meist auf der Verkaufsseite am breitesten, bei Rechnungen und Kundenaufträgen, und im Einkauf am dünnsten, wo eine Bestellung oft gar kein Event hat. Damit fahren Sie Webhooks und Abfragen nebeneinander in derselben Anbindung, für denselben Kunden, mit zwei Codepfaden, die unterschiedlich scheitern. Synthetische Events nehmen diese Teilung weg: Ein Objekt ohne natives Event kommt genauso an wie eines mit.
Sie abonnieren einmal und empfangen Events. Das Abfragen, die Taktung und die Änderungserkennung bleiben auf Maesns Seite, und der Event-Rumpf ist der, den Sie schon verarbeiten.
Eine Callback-URL ist öffentlich, deshalb wird jedes Event signiert
Events überall auszuliefern löst die Abdeckung. Es löst nicht das Vertrauen, und den Endpunkt, den Sie eben veröffentlicht haben, erreicht jeder, der die URL erfährt.
Ein unauthentifizierter Webhook-Endpunkt ist eine offene Tür: Wer die URL erfährt, kann ein gefälschtes Event darauf senden, und ein Handler, der auf Empfangenes reagiert, bucht es bereitwillig. Jedes Event, das Maesn ausliefert, nativ oder synthetisch, trägt einen über dem Rohrumpf berechneten X-MAESN-SIGNATURE-Header, Ihr Endpunkt kann also feststellen, dass das Event von Maesn kam, bevor er irgendetwas damit tut.
Über dem Rohrumpf neu berechnen
Nehmen Sie das Secret aus dem Anlegen des Webhooks, und tun Sie es, bevor Sie das JSON parsen. Wer vorher neu serialisiert, ändert die Bytes, und die Signatur passt nie.
expected = hmacSha256(webhookSecret, rawBody)
In konstanter Zeit vergleichen
Ein einfacher Gleichheitsvergleich verrät über die Laufzeit Information. Beide Hex-Strings in konstanter Zeit zu vergleichen ist eine kleine, kostenlose Härtung.
isValid = timingSafeEqual(expected, header) // not: expected === header
Die Verarbeitung idempotent schlüsseln
Netze wiederholen, dasselbe Event kann also zweimal ankommen. Schlüsseln Sie Ihre Verarbeitung so, dass eine erneute Bearbeitung harmlos ist, dann wird aus doppelter Zustellung keine doppelte Buchung.
key = `${eventType}:${resource}:${resourceId}`Zusammengenommen ist das eine Haltung und nicht drei Funktionen. Ping and Pull heißt, dass ein ausgeliefertes Event Kennungen trägt und keine Geschäftsdaten, selbst ein abgefangenes Event gibt also sehr wenig preis. Die Signatur heißt, dass Sie einem Event trauen können, bevor Sie handeln. Und weil Maesn keine Kopie der durchgereichten Daten behält, ist die Plattform in der Mitte kein zweiter Ort, an dem die Datensätze Ihrer Kunden liegen. Wer beantworten muss, wie das abgesichert ist, gibt auf jeder Ebene dieselbe Antwort, und darum geht es auch bei die umfassendere Sicherheitsarchitektur.
Bescheid, wenn der API-Aufruf wirklich fertig ist
Nicht jedes System beantwortet einen Schreibvorgang sofort. Manche nehmen das Objekt an, reihen es ein und erzeugen den Ausgang später, und dann fragen Sie normalerweise Ihr eigenes Ergebnis ab.
Maesn kann diese Schleife mit einem Webhook schließen: Sobald das System den Ausgang erzeugt, bekommen Sie ein Event, das sagt, ob der Schreibvorgang gelang oder scheiterte. Es gibt das, weil Kunden danach gefragt haben, und das ist der ehrliche Grund, aus dem das meiste dieser Ebene existiert. Jede Anfrage, jede Antwort und jedes Event auf dem Weg wird aufgezeichnet, wenn also doch etwas schiefgeht, sehen Sie über Protokollierung und Monitoring, was gesendet wurde und was zurückkam.
Ein Listener, jedes System
- Jedes Event-Modell einzeln lernen
- Die stummen Systeme selbst abfragen
- Pings in echte Nutzlasten verwandeln
- Jedes Schema anders prüfen
- Ein Event-Modell zu verarbeiten
- Stumme Systeme für Sie abgefragt
- So oder so normalisierte Nutzlasten
- Überall eine Signaturprüfung
Webhook-Unterstützung fehlt am ehesten in dem System, das ein Kunde als nächstes will, und erzwingt am ehesten eine Neuschreibung, wenn sie fehlt. Weil das Event-Modell Maesns ist und nicht das jedes Herstellers, spielt diese Frage im Verkaufsgespräch keine Rolle mehr: Sie unterstützen das System, und wie seine Daten zu Ihnen kommen, ist ein Umsetzungsdetail auf unserer Seite. Der Handler, den Sie für die erste Anbindung geschrieben haben, ist der Handler für die letzte. Welches System ein Interessent fährt, ist dann eine Frage, die Go-to-Market-Teams beantworten, ohne vorher in der Entwicklung nachzufragen.
Häufige Fragen
Wie richte ich einen Webhook mit Maesn ein?
Wie sieht ein Event aus?
Was sind synthetische Webhooks?
Welche ERP- und Buchhaltungssysteme unterstützen eigene Webhooks und Trigger?
Was unterscheidet app-basierte von nutzerbasierten Webhooks?
Was sind virtuelle Webhooks?
Websockets oder Webhooks für ERP-Anbindungen?
Wie härte ich meinen Webhook-Handler ab?
Wie prüfe ich, dass ein Event wirklich von Maesn kam?
Was passiert, wenn ein System eine Anfrage asynchron verarbeitet?
Sollte ich Webhooks nutzen oder abfragen?
Welche Events kann ich abonnieren?
Einmal bauen, auf der Unified API.
Sehen Sie, wie das Unified-Webhook-Modell für Ihre Integration funktioniert, oder steigen Sie in die technische Referenz ein.