InnerWeb
Zum Inhalt springen

Idempotenter Webhook-Empfänger: Bewährte Praktiken

Der Empfänger von Webhooks in einem Sicherheitssystem muss davon ausgehen, dass dasselbe Ereignis zweimal eintrifft. Wiederholungen sind ein Merkmal der Zustellmechanismen, kein Fehler. Ein idempotenter Empfänger verarbeitet eine Wiederholung ohne Nebenwirkungen: Er verdoppelt weder den Alarm noch den Eintrag im Kanal noch die Meldung in einem externen System.

300 s
danach kehrt die Reservierung in den Pool zurück
Quelle: karta
5 s
Zeitgrenze für den Versand der Ereignisse der Rezeption
Quelle: karta
89
Einträge in einem Paket
Quelle: karta

Warum Wiederholungen normal sind

Im Modus outbox wird ein Eintrag im Zustand der Zustellung, dessen Reservierung länger als 300 Sekunden dauert, in den Pool zurückgegeben und kann erneut abgeholt werden. Eine fehlgeschlagene Bestätigung setzt den Eintrag in den Zustand wartend zurück und erhöht den Versuchszähler. Bei dieser Konstruktion sieht der Endempfänger dieselbe Nutzlast von Zeit zu Zeit ein zweites Mal, und keiner dieser Mechanismen ist ein Fehler.

Die Garantie lautet daher mindestens einmal, nicht genau einmal. Für einen Alarm ist das die richtige Wahl: Lieber zweimal einen Alarm erhalten als gar keinen. Der Preis dieser Wahl fällt auf den Empfänger, der gegen Wiederholungen unempfindlich sein muss.

Praktiken 1 bis 3: Schlüssel des Ereignisses und Markierung

Erste Praktik: Legen Sie den Schlüssel fest, der das Ereignis eindeutig kennzeichnet. Am besten ist eine Verbindung aus Typ des Ereignisses, Kennung des Objekts und Zeitpunkt des Ereignisses. Bei den Ereignissen der Rezeption enthält jede Nutzlast die Zeit im Format ISO 8601 in der Zeitzone Europe/Warsaw, was einen solchen Schlüssel ohne Rückfrage beim Quellsystem ermöglicht.

Zweite: Schreiben Sie die Markierung der Verarbeitung atomar, bevor Sie die Nebenwirkung auslösen. Das im System selbst verwendete Muster ist die Markierung SET NX in Redis, die Dubletten des Alarms über das Nichtbestehen einer Unterweisung blockiert. Das Setzen der Markierung ist eine atomare Operation: Nur der erste Empfänger legt sie an, jeder weitere sieht, dass der Eintrag belegt ist.

Dritte: Geben Sie die Markierung frei, wenn die Ausführung fehlgeschlagen ist. Das System verfährt genau so: Ein fehlgeschlagener Versand gibt die Sperre frei, damit der Alarm erneut gesendet werden kann. Ein Empfänger, der ein Ereignis vor der Ausführung der Aktion als erledigt markiert und die Markierung nach einem Fehler nicht zurücknimmt, verwandelt einen vorübergehenden Ausfall in einen dauerhaften Verlust des Alarms.

Parameter, von denen die Wiederholungen abhängen

Parameter, von denen die Wiederholungen abhängenBalkendiagramm: 300 Sekunden bis zur Rückgabe der Reservierung, 89 Einträge im Paket, Grenze für den Versand 5 Sekunden.0100200300WertSekunden bis zur Rückgabe derReservierungSekunden bis zur Rückgabe der Reservierung: 300 Wert300Einträge im PaketEinträge im Paket: 89 Wert89Grenze Versand Rezeption (s)Grenze Versand Rezeption (s): 5 Wert5
Quelle: Beschreibungen der Funktionen Webhook Outbox und Reception Events Webhook (Produktdokumentation)

Praktiken 4 und 5: Bestätigungen und Reihenfolge

Vierte: Bestätigen Sie die Zustellung am Ende und rechnen Sie mit der Idempotenz der Bestätigung. Die Bestätigung nimmt den Status delivered oder failed mit einer optionalen Fehlerbeschreibung entgegen, und die Bestätigung eines bereits zugestellten Eintrags ändert nichts. Der Empfänger kann eine Bestätigung nach dem Verlust einer Netzantwort daher gefahrlos wiederholen.

Fünfte: Gehen Sie nicht von einer Reihenfolge aus. Das Abholen eines Pakets reserviert bis zu 89 Einträge atomar, die Reihenfolge der Zustellung an die Endempfänger hängt aber vom Poller und vom Netz ab. Ereignisse über eine Änderung des Zustands (Aktualisierung einer Gruppe, danach Abbruch) sollte der Empfänger anhand des Zeitpunkts des Ereignisses vergleichen, nicht anhand der Reihenfolge des Eintreffens.

Praktiken 6 und 7: Widerstandsfähigkeit und Nachvollziehbarkeit

Sechste: Ein Fehler des Empfängers darf die Quelle nicht anhalten. Das System sendet die Ereignisse der Rezeption asynchron mit einer Zeitgrenze von 5 Sekunden, damit ein Ausfall des Webhooks die Anmeldung eines Gastes nicht unterbricht. Der Empfänger sollte auf seiner Seite schnell antworten und die schwere Aktion im Hintergrund verarbeiten, statt die Verbindung bis zum Ende einer komplizierten Aktion offen zu halten.

Siebte: Protokollieren Sie jedes Ereignis mit Schlüssel und Ergebnis (verarbeitet, als Dublette übersprungen, Fehler). Ohne das lässt sich der Verlust einer Nachricht nicht von der korrekten Ablehnung einer Wiederholung unterscheiden. Bei Integrationen mit einem Protokoll des Austauschs sollte dieser Eintrag getrennt vom Protokoll der Anwendung geführt werden.

Typische Fehler bei Empfängern

Der häufigste Fehler ist die Deduplizierung anhand des Textes der Nachricht statt anhand des Schlüssels des Ereignisses: Zwei verschiedene Alarme mit demselben Text werden dann zu einem zusammengeführt. Der zweite ist eine Markierung ohne Lebensdauer, die nach einem Neustart eine erneute Verarbeitung erlaubt. Der dritte ist die Bestätigung der Zustellung vor der Ausführung der Aktion, wodurch eine fehlgeschlagene Aktion nie wiederholt wird.

Bevor Sie den Empfänger in der Produktivumgebung in Betrieb nehmen, senden Sie dasselbe Ereignis zweimal und prüfen Sie, ob im Kanal ein Eintrag erscheint und im Protokoll ein Eintrag über die Verarbeitung und ein Eintrag über das Überspringen.

Checkliste

Videomaterial

Häufig gestellte Fragen

Garantiert das System die Zustellung genau einmal?

Nein. Die Wiederholungsmechanismen liefern die Zustellung mindestens einmal, daher sollte der Empfänger idempotent sein.

Womit werden Ereignisse am besten dedupliziert?

Mit einem Schlüssel aus Typ des Ereignisses, Objekt und Zeitpunkt des Ereignisses. Der Text der Nachricht ist kein guter Schlüssel.

Was ist, wenn der Empfänger die Zustellung zweimal bestätigt?

Das ist unbedenklich. Die Bestätigung eines bereits zugestellten Eintrags ändert nichts.

Ein Empfänger, der Wiederholungen verkraftet

Wir gehen mit Ihrem Integrator den Test mit einem doppelten Ereignis und das Protokoll der Verarbeitung durch.

Sprechen wir