Neu: Die KI-Firewall überwacht die gesamte Plattform und erklärt jeden Vorfall in einfachen Worten. So funktioniert es

Webhook-Wiederholungen und Idempotenz: Ereignisse empfangen, ohne die Arbeit doppelt auszuführen

Warum Sender wiederholen, warum eine Queue und ein eindeutiger Schlüssel auf der Delivery-ID doppelte Arbeit verhindern und wie Sie den Handler testen, bevor er live geht.

Webhook-Wiederholungen und Idempotenz gehören zusammen. Ein Sender, der nicht rechtzeitig eine 2xx-Antwort erhält, sendet dasselbe Ereignis erneut, daher sieht Ihr Empfänger ein Ereignis manchmal zweimal. Machen Sie den Handler idempotent: Antworten Sie schnell, stellen Sie die Arbeit in eine Queue und speichern Sie jede Delivery-ID, damit ein Wiederholungsaufruf erkannt und übersprungen wird.

Auf der Empfängerseite einer Integration behandle ich jeden Webhook so, als könnte er mehrfach eintreffen. Ein Handler, der die ganze Arbeit innerhalb der Anfrage erledigt, wird sie früher oder später zweimal ausführen.

Warum wiederholen Webhook-Sender dasselbe Ereignis?

Ein Sender wiederholt, weil er nicht unterscheiden kann, ob die Anfrage oder die Antwort verloren ging. Hat Ihr Server die Arbeit erledigt und dann brach die Verbindung ab, oder kam Ihre Antwort nach dem Timeout des Senders an, verbucht der Sender einen Fehler und sendet das Ereignis erneut.

RFC 9110, der Standard zur HTTP-Semantik, führt PUT, DELETE und die sicheren Methoden als idempotent auf; POST gehört nicht dazu. Ein Client sollte eine nicht idempotente Anfrage nicht automatisch wiederholen, sofern er nicht weiß, dass die Anfrage idempotent ist, oder erkennen kann, dass das Original nie angewendet wurde. Ein Sender, der einen POST wiederholt, verlässt sich darauf, dass der Empfänger ihn idempotent macht, und eine Delivery-ID, die bei jedem Versuch gleich bleibt, ermöglicht ihm genau das.

Warum eine Queue für Webhooks verwenden?

Eine Queue erlaubt dem Handler, innerhalb von Millisekunden zu antworten und die langsame Arbeit danach zu erledigen, sodass das Timeout des Senders nie mit Ihrer Geschäftslogik um die Wette läuft.

  1. Prüfen Sie die Signatur gegen den unveränderten Rohtext, sofern der Sender seine Aufrufe signiert.
  2. Fügen Sie die Delivery-ID und den unveränderten Rohtext in eine Tabelle mit einem eindeutigen Schlüssel auf der Delivery-ID ein.
  3. Antworten Sie mit 2xx. RFC 9110 definiert für diesen Fall 202 Accepted: zur Verarbeitung angenommen, Verarbeitung noch nicht abgeschlossen.
  4. Ein Worker liest das gespeicherte Ereignis, führt die Arbeit aus und markiert die Zeile als erledigt.

Verletzt das Einfügen den eindeutigen Schlüssel, liegt das Ereignis bereits vor: Antworten Sie mit 2xx und tun Sie sonst nichts. Eine Fehlerantwort auf ein Duplikat bringt nur weitere Wiederholungen. Es ist dieselbe Idee wie der eindeutige Schlüssel aus Gerät und Zeitstempel in einem MQTT-Datenbank-Writer. Schlägt das Einfügen fehl, weil die Datenbank nicht erreichbar ist, antworten Sie mit einem Fehler, damit der Sender es später erneut versucht.

Was passiert, wenn ein Webhook-Endpunkt ausfällt?

Der Sender wiederholt nach eigenem Zeitplan und hört dann auf. Anzahl der Versuche und Wartezeiten unterscheiden sich von Sender zu Sender. Lesen Sie daher die Dokumentation des Senders, bevor Sie ein Wartungsfenster planen.

Wiederholte Ereignisse kommen verspätet und können in falscher Reihenfolge eintreffen. Sortieren Sie sie daher nach den Zeitstempeln im Payload und nicht nach der Eingangsreihenfolge. Bei einem langen Ausfall nutzen Sie einen Catch-up-Abruf über die API des Senders, wie in Webhook vs. WebSocket vs. Polling beschrieben.

Hermetry verbindet Feldgeräte mit Live-Dashboards, Regeln und Alarmen: IoT-Telemetrie und SCADA in einer Plattform. Seine Webhooks tragen eine X-Webhook-Delivery-ID, die bei jedem Retry und jeder erneuten Zustellung gleich bleibt. Zustellungen erfolgen mindestens einmal, ohne garantierte Reihenfolge. Standardmäßig hat eine Zustellung 3 Versuche, den ersten eingeschlossen, mit Wartezeiten von 60.000 ms und 300.000 ms vor den Wiederholungen. Nach 10 aufeinanderfolgenden Fehlern wird der Endpunkt abgeschaltet; sobald ein Administrator ihn wieder einschaltet, können die fehlgeschlagenen Ereignisse erneut zugestellt oder wiedergegeben werden.

Bevor Sie den Worker schreiben, schauen Sie in der Ereignisdokumentation des Senders nach, etwa in einer Webhook-Ereignisreferenz, welches Feld die Ereigniszeit enthält.

Wie testen Sie einen Webhook auf localhost?

Ein Sender im Internet kann localhost nicht erreichen. Spielen Sie daher zuerst aufgezeichnete Payloads gegen Ihren lokalen Handler ab und führen Sie danach eine End-to-End-Prüfung über eine öffentliche HTTPS-Adresse durch.

  • Zeichnen Sie eine echte Zustellung mit Headern und unverändertem Rohtext auf und spielen Sie sie zweimal mit einem Kommandozeilen-HTTP-Client ab. Der zweite Aufruf sollte mit 2xx beantwortet werden und keinerlei Nebenwirkung auslösen.
  • Wenn Ihr Handler alte Zeitstempel ablehnt, signieren Sie die Wiederholungen mit einem Test-Secret und senden Sie einen veralteten Zeitstempel, um zu prüfen, dass er abgewiesen wird.

Ein Tunnel, der Ihrem Rechner eine temporäre öffentliche HTTPS-Adresse gibt, deckt die End-to-End-Prüfung ab. Ich schließe ihn, wenn der Test bestanden ist.

Häufig gestellte Fragen

Ist ein Webhook-POST standardmäßig idempotent?

Nein. RFC 9110 führt PUT, DELETE und die sicheren Methoden als idempotent auf, POST gehört nicht dazu. Ein Webhook-POST wird nur dann idempotent, wenn der Empfänger ihn dazu macht, etwa indem er die Delivery-ID unter einem eindeutigen Schlüssel speichert und Wiederholungen überspringt.

Wie lange sollte ich Delivery-IDs aufbewahren?

Mindestens so lange, wie der Sender das Ereignis noch wiederholen oder erneut zustellen kann. Eine manuelle erneute Zustellung, sofern ein Sender sie anbietet, kann Tage später erfolgen. Jede ID ist eine kurze Zeichenkette, daher bewahre ich sie wochenlang auf.

Kann ich anhand des Payloads statt einer Delivery-ID deduplizieren?

Nur als Notlösung. Zwei echte Ereignisse können identische Payloads haben, etwa wenn ein Wert zweimal dieselbe Grenze überschreitet. Ohne Delivery-ID bilden Sie einen Schlüssel aus Ereignistyp, Quell-ID und dem eigenen Zeitstempel des Ereignisses.

Teilen

Sehen Sie diese Woche Ihre Felddaten live

Starten Sie eine Testphase in Ihrer Region mit Ihren ersten Geräten oder buchen Sie eine Demo und bringen Sie Ihren eigenen Anwendungsfall mit.