Ein Webhook ist eine Benachrichtigung aus einem anderen System. Es ist verlockend, diese Benachrichtigung als eine streng geordnete Anweisung zu betrachten: empfangen, einen Datensatz aktualisieren und Erfolg zurückmelden. Echte Integrationen erfordern jedoch eine sorgfältigere Vereinbarung.
Dasselbe Ereignis kann mehrmals eintreffen. Ein späteres Ereignis kann zuerst eintreffen. Der Absender kann einen erneuten Versuch unternehmen, weil er die Antwort nie erhalten hat, selbst wenn der Empfänger seine Arbeit bereits abgeschlossen hat. Ich berücksichtige diese Bedingungen von Anfang an bei meiner Entwicklung.
Halten Sie die Empfangsgrenze klein
Der Empfänger sollte den Empfang bestätigen, die grundlegende Form der Übermittlung überprüfen, diese dauerhaft speichern und gemäß dem Protokoll des Anbieters bestätigen. Aufwändige geschäftliche Verarbeitungsschritte können erst danach erfolgen.
Bei der Signaturprüfung muss die vom Anbieter vorgeschriebene Darstellung verwendet werden. Wenn die Signatur die ursprünglichen Anforderungsbytes überdeckt, kann das vorherige Parsen und erneute Serialisieren von JSON dazu führen, dass sich der zu prüfende Inhalt ändert. Fehler bei der Signaturprüfung sollten niemals in die normale Verarbeitung durchschlagen.
Ebenso wichtig ist die Ausfallsicherheit. Wenn eine Bestätigung erst nach der Aufzeichnung des Ereignisses zurückgesendet wird, entsteht ein Zeitfenster, in dem der Prozess abstürzen und Daten verloren gehen können, von denen der Absender annimmt, dass sie bereits angenommen wurden. Eine In-Memory-Warteschlange schließt dieses Zeitfenster nicht.
Beleg- und Geschäftsvorgänge deduplizieren
Ich speichere den Anbieter, das verknüpfte Konto und die Ereignis-ID unter einer Eindeutigkeitsbeschränkung in der Datenbank. Dadurch werden gleichzeitig stattfindende doppelte Einlieferungen in einem einzigen gespeicherten Beleg zusammengefasst.
Eine Ereignis-ID entspricht jedoch nicht immer einer Geschäftsvorgangs-ID. Zwei unterschiedliche Ereignisse können durchaus dieselbe Ressource beschreiben oder dieselbe nachgelagerte Aktion auslösen. Der Geschäftsvorgang benötigt eine eigene Identität und eigene Übergangsregeln.
In der Webhook-Dokumentation von Stripe werden doppelte Zustellungen ausdrücklich beschrieben, und es wird keine bestimmte Reihenfolge der Zustellungen garantiert. Ich nutze diese dokumentierten Verhaltensweisen als Grundlage für das Design des Empfängers, anstatt davon auszugehen, dass der in einer Entwicklungssitzung beobachtete Zeitablauf verbindlich ist.
Modellierung von Zustandsübergängen anstelle der Ankunftsreihenfolge
Ziehen Sie eine Abonnement-Integration in Betracht. Eine verspätete Benachrichtigung sollte einen aktuelleren Zustand nicht blind überschreiben. Manchmal besteht die richtige Vorgehensweise darin, die maßgebliche aktuelle Ressource abzurufen und die lokale Ansicht anzupassen.
Bei Vorgängen, die historische Übergänge erfordern, behalte ich das Ereignis bei und wende domänenspezifische Regeln an. Ein Zeitstempel allein reicht möglicherweise nicht aus, um eine Reihenfolge festzulegen, insbesondere wenn mehrere Änderungen denselben Zeitstempel aufweisen oder verschiedene Systeme unterschiedliche Uhren verwenden.
Die Entscheidung hängt vom Verwendungszweck der Daten ab. Ein lokales Status-Abzeichen benötigt möglicherweise nur den aktuellen Status. Ein Hauptbuch oder ein Prüfprotokoll benötigt hingegen die tatsächliche Abfolge und Bedeutung der Änderungen. Ein einziger allgemeiner „Last-Write-Wins“-Handler kann beiden Zwecken nicht zuverlässig gerecht werden.
Verarbeitungsfehler sichtbar machen
Ich unterscheide zwischen dem Empfangsstatus und dem Bearbeitungsstatus. Ein akzeptiertes Ereignis kann sich noch in der Warteschlange befinden, erneut versucht werden, abgeschlossen sein oder auf eine Überprüfung warten. Diese Unterscheidung verhindert, dass eine gute HTTP-Antwortquote eine fehlerhafte Integration verschleiert.
Für jeden Verarbeitungsversuch sollte es eine Richtlinie für begrenzte Wiederholungsversuche geben. Wenn der Vorgang nicht fortgesetzt werden kann, sollten die Ereignisreferenz und der Grund für den Fehler in einer Überprüfungs- oder Dead-Letter-Warteschlange gespeichert werden. Bei der erneuten Ausführung sollten dieselben Regeln zur Duplikatserkennung und Autorisierung wie beim ursprünglichen Versuch angewendet werden.
Zu den nützlichen Kennzahlen zählen das Alter des ältesten noch nicht verarbeiteten Ereignisses, die Verarbeitungslatenz, wiederholte Fehler und Abgleichabweichungen. Sie geben die tatsächliche Verzögerung für den Kunden deutlicher wieder als die Gesamtzahl der Webhook-Anfragen.
Testen Sie, was das Netzwerk alles kann
Meine Testsequenz umfasst doppelte Zustellungen, eine umgekehrte Reihenfolge der Eingänge, einen Absturz nach einer dauerhaften Empfangsbestätigung sowie ein Timeout nach einem externen Nebeneffekt. Außerdem überprüfe ich, dass eine ungültige Signatur nicht einmal einen ausstehenden Geschäftsvorgang erzeugen kann.
Ein gut konzipierter Webhook-Empfänger liefert dem Team zwei nützliche Informationen: ob die Benachrichtigung erfolgreich empfangen wurde und ob der beabsichtigte Geschäftsprozess abgeschlossen wurde. Die Trennung dieser beiden Informationen erleichtert den Betrieb der Integration erheblich.
Aktualisiert am 25. September 2026.