Was ist Idempotenz, und wie gehe ich mit doppelten Webhooks um?

Eine abgebrochene Verbindung kann dazu führen, dass Sie nicht wissen, ob eine Sendeanfrage erfolgreich war. Eine verlorene Bestätigung kann auch dazu führen, dass ein Webhook-Sender ein Event zustellt, das Ihre Anwendung bereits gespeichert hat.

Diese Fehler treten in entgegengesetzten Richtungen auf. Bird kann eine wiederholte API-Anfrage anhand eines von Ihnen gelieferten Schlüssels erkennen. Ihr Webhook-Empfänger braucht einen eigenen Datensatz der Events, die er bereits akzeptiert hat.

Wie wiederhole ich einen Versand sicher?

Verwenden Sie denselben Idempotency-Key-Header für jeden Versuch einer logischen API-Operation.

Sie wählen den Schlüssel mit bis zu 255 Zeichen und behalten ihn über Wiederholungen hinweg bei. Ein stabiler Wert wie welcome-user/usr_abc123 kann eine Willkommensnachricht-Operation auch nach einem Neustart Ihres Prozesses identifizieren.

Der Header gilt für mutierende Anfragen wie POST, PATCH und DELETE. Eine Anfrage ohne Schlüssel wird ohne diese Deduplizierung verarbeitet. GET ignoriert den Header, weil das Lesen der Ressource bereits sicher wiederholbar ist.

Bird gibt die gespeicherte Antwort für eine übereinstimmende abgeschlossene Anfrage zurück, einschließlich ihres ursprünglichen Status und Bodys. Die Antwort enthält Idempotency-Replay: true, sodass Sie die Wiederverwendung in Ihren Logs erkennen können.

Der Idempotenz-Leitfaden dokumentiert ein Standardfenster von drei Stunden für die gespeicherte Antwort. Ein erneuter Versuch nach Ablauf dieses Fensters kann als neue Operation ausgeführt werden. Verlassen Sie sich nicht dauerhaft auf diesen Schlüssel, um doppelte Sendungen zu verhindern.

Bird-SDKs erzeugen einen Schlüssel für eine Mutation und verwenden ihn bei ihren internen Wiederholungen wieder. Die Bird CLI erzeugt ebenfalls einen Schlüssel für eine mutierende Anfrage, wenn keiner vorhanden ist. Setzen Sie --idempotency-key explizit, wenn separate Befehlsaufrufe dieselbe Operation teilen müssen.

Verwenden Sie für die SMTP-Einreichung den X-Bird-Idempotency-Key-Nachrichtenheader. Damit kann eine wiederholte Einreichung dieselbe Operation identifizieren.

Was passiert, wenn ich einen Schlüssel falsch wiederverwende?

Bird lehnt eine widersprüchliche Schlüsselverwendung ab, statt eine Antwort für eine andere Operation zurückzugeben.

Der Vergleich umfasst Methode, Endpunkt, Pfadparameter, Query-String und Body. Bei JSON verändert geänderter Whitespace die Anfrage-Identität – bewahren Sie den ursprünglichen Body bei Wiederholungen unverändert.

Die Sperre einer unvollendeten Operation läuft innerhalb von dreißig Sekunden ab. Dieses Limit ermöglicht es einer weiteren Anfrage, nach einer abgebrochenen Operation fortzufahren. Es stellt nicht fest, ob ein Seiteneffekt bereits eingetreten ist.

Bird speichert keine 5xx-Antwort zur Wiedergabe. Versuchen Sie einen Serverfehler oder Timeout mit demselben Schlüssel erneut, damit ein aufgezeichneter Erfolg weiterhin wiederverwendet werden kann.

Eine Validierungs- oder Geschäftsregel-Ablehnung gibt den Schlüssel frei. Sie können die abgelehnte Anfrage korrigieren und mit demselben Schlüssel erneut versuchen, weil keine abgeschlossene Antwort gespeichert wurde.

Warum erhalte ich denselben Webhook zweimal?

Bird kann ein Event, das Ihr Empfänger bereits gespeichert hat, erneut senden, wenn keine erfolgreiche Antwort empfangen wurde.

Ein Empfänger kann ein Event speichern, kurz bevor seine Verbindung abbricht. Bird sieht keine erfolgreiche Bestätigung und versucht es erneut, obwohl der Empfänger das Event bereits hat.

Jede Wiederholung behält denselben webhook-id-Header bei, der das Event identifiziert. Auch eine erneute Zustellung einer verpassten Lieferung behält diesen Bezeichner bei, sodass beide als dasselbe Event erkannt werden können.

Wie mache ich meinen Handler idempotent?

Speichern Sie jede webhook-id unter einem eindeutigen Datenbank-Constraint, bevor Sie die Arbeit des Events einplanen.

Eine Prüfung auf eine vorhandene Zeile vor dem Einfügen hinterlässt eine Race Condition: Zwei gleichzeitige Anfragen können beide keine Zeile sehen. Lassen Sie die Datenbank doppelte Bezeichner ablehnen.

Speichern Sie den Bezeichner und den Job in derselben Transaktion. Das verhindert, dass ein Bezeichner ohne eingereihte Arbeit gespeichert wird.

1. Verifizieren Sie die Anfrage und fügen Sie dann deren Bezeichner und Job in derselben Transaktion ein.
2. Geben Sie 2xx zurück, nachdem die Transaktion committed wurde, damit Bird die Wiederholungen einstellen kann.
3. Verarbeiten Sie den gespeicherten Job in einem Worker, der seine eigenen Aktionen sicher wiederholen kann.

Geben Sie bei einem bereits committeten doppelten Bezeichner Erfolg zurück, ohne einen weiteren Job zu erstellen. Geben Sie bei einer fehlgeschlagenen Transaktion einen Fehler zurück, damit Bird es erneut versucht.

Halten Sie langsame Arbeit vom Empfänger fern, weil das Warten darauf ein Timeout der Anfrage verursachen kann. Ein Worker kann aus Gründen erneut versuchen, die nichts mit der Webhook-Zustellung zu tun haben – daher reicht es nicht aus, nur den Empfänger zu schützen.

Events können auch in falscher Reihenfolge eintreffen. Vergleichen Sie Event-Zeiten in timestamp, bevor Sie neueren Zustand überschreiben. Fehlgeschlagene Webhook-Wiederholungen enthält das Beispiel mit Teilkosten.

Worauf sollte ich mich nicht verlassen?

Gehen Sie nicht davon aus, dass Anfrage-Deduplizierung doppelte Seiteneffekte unmöglich macht.

Wenn der Deduplizierungs-Store von Bird nicht verfügbar ist, werden Anfragen ohne ihn verarbeitet. Halten Sie eine Absicherung auf Geschäftslogikebene bereit, wo die Wiederholung einer Aktion schädlich wäre.

Ebenso unterscheidet webhook-id wiederholte Zustellungen eines Events. Separate Events haben separate Bezeichner. Ihre Anwendung entscheidet weiterhin, ob diese Events die Wiederholung derselben Aktion rechtfertigen.

Idempotenz dokumentiert das Wiederholungsverhalten von API. Webhooks behandelt die separaten Zustellungsgarantien, die Ihr Empfänger handhabt.