Webhooks sind einfach zu bauen und schwer richtig zu bauen. Der Unterschied zeigt sich nicht am ersten Tag, sondern in dem Moment, in dem ein Empfänger für zwei Stunden nicht erreichbar ist oder eine Zahlung doppelt verarbeitet wird.
Die folgenden Punkte trennen eine funktionierende Umsetzung von einer, die nur meistens funktioniert.
Empfangen: einmal ist nicht garantiert
Wer Webhooks empfängt, muss davon ausgehen, dass dieselbe Nachricht mehrfach ankommt. Das ist kein Fehler des Senders, sondern die Folge davon, dass ein Sender nach einer ausbleibenden Antwort nicht wissen kann, ob die Nachricht angekommen ist.
Die Konsequenz ist, dass die Verarbeitung mehrfach ausführbar sein muss, ohne zusätzlichen Effekt. Der übliche Weg ist eine eindeutige Kennung je Nachricht, die vor der Verarbeitung in einer Tabelle abgelegt wird — mit einer Eindeutigkeitsbedingung, sodass der zweite Versuch scheitert statt doppelt zu buchen.
Ebenso wenig ist die Reihenfolge garantiert. Eine Nachricht über eine Kündigung kann vor der Nachricht über die Verlängerung eintreffen. Wo die Reihenfolge zählt, hilft ein Zeitstempel oder ein Versionszähler im Nutzdatensatz, gegen den geprüft wird.
Empfangen: erst prüfen, dann glauben
Ein Webhook-Endpunkt ist öffentlich erreichbar. Ohne Prüfung der Signatur kann jeder Ereignisse einliefern — etwa eines, das ein Abonnement auf bezahlt setzt.
Die Prüfung muss gegen den unveränderten Rohtext der Anfrage erfolgen, nicht gegen das bereits geparste Objekt. Das ist die häufigste Fehlerquelle, weil viele Rahmenwerke den Text automatisch verarbeiten, bevor der eigene Code ihn sieht.
Ebenfalls zu prüfen ist der Zeitstempel, um das erneute Einspielen alter, gültig signierter Nachrichten zu verhindern.
Empfangen: schnell antworten, langsam arbeiten
Der Endpunkt sollte die Nachricht entgegennehmen, ihre Echtheit prüfen, sie ablegen und antworten. Die eigentliche Verarbeitung gehört in einen nachgelagerten Vorgang.
Der Grund ist praktisch: Sender haben Zeitgrenzen. Eine Verarbeitung, die eine E-Mail versendet und drei fremde Schnittstellen aufruft, überschreitet sie irgendwann — und dann gilt die Zustellung als gescheitert, obwohl die Arbeit getan wurde. Die Folge sind Wiederholungen und doppelte Effekte.
Senden: Wiederholung mit wachsendem Abstand
Wer Webhooks anbietet, braucht eine Wiederholungslogik. Sofortige Wiederholung hilft nicht, wenn der Empfänger überlastet ist; sie verschlimmert die Lage.
Üblich sind wachsende Abstände über mehrere Stunden bis Tage, mit einer zufälligen Streuung, damit nicht alle Empfänger gleichzeitig erneut angesprochen werden. Nach einer festgelegten Zahl von Versuchen wandert die Nachricht in eine Ablage für Fehlgeschlagenes.
Diese Ablage braucht eine Oberfläche. Eine Fehlerwarteschlange, die niemand ansieht, ist ein stiller Datenverlust mit zusätzlichen Schritten.
Senden: dem Empfänger das Leben leicht machen
Drei Dinge unterscheiden eine gute Webhook-Schnittstelle von einer lästigen. Erstens eine stabile, dokumentierte Nutzdatenstruktur mit einer Versionsangabe — Änderungen daran brechen bei allen Empfängern gleichzeitig.
Zweitens eine Möglichkeit, vergangene Ereignisse abzurufen. Wenn ein Empfänger einen Ausfall hatte, will er nachholen, statt Sie um eine erneute Zustellung zu bitten.
Drittens eine Möglichkeit, ein Testereignis auszulösen. Wer eine Integration baut, braucht das am ersten Tag, und ohne dieses Werkzeug landet die Anfrage in Ihrem Support.
Nutzdaten: dünn oder dick
Zwei Ansätze stehen zur Wahl. Dünne Nachrichten enthalten nur eine Kennung, und der Empfänger holt den aktuellen Zustand selbst. Dicke Nachrichten enthalten den vollständigen Datensatz.
Dünne Nachrichten lösen das Reihenfolgeproblem elegant, weil der Empfänger immer den aktuellen Stand liest, und sie geben weniger preis. Dafür erzeugen sie Rückfragen und funktionieren nicht, wenn der Empfänger den Zustand zum Zeitpunkt des Ereignisses braucht.
Für die meisten Fälle ist ein Mittelweg tragfähig: die wichtigsten Felder mitsenden und eine Verweisadresse für den vollständigen Datensatz mitgeben.
Was man am ersten Tag einbaut
Eine Protokollierung jeder ein- und ausgehenden Nachricht mit Zeitpunkt, Antwortcode und Nutzdaten. Ohne dieses Protokoll ist jede Fehlersuche in einer Integration ein Ratespiel — und Fehlersuche in Integrationen ist der Dauerzustand.