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 kann ich einen Versand sicher erneut versuchen?
Verwenden Sie bei jedem erneuten Versuch denselben Idempotency-Key und eine identische Anfrage. Die Garantie lautet genau einmalige Annahme: Übereinstimmende erneute Versuche innerhalb von drei Stunden führen zu einer einzigen angenommenen Operation, auch wenn Ihnen deren Antwort verloren gegangen ist.
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.
| Situation | Antwort und Abhilfe |
|---|---|
| Gleicher Schlüssel und gleiche Anfrage, Antwort gespeichert | Die gespeicherte Antwort innerhalb der Aufbewahrungsdauer, mit Idempotency-Replay: true. |
| Abgeschlossener Schlüssel für eine andere Anfrage wiederverwendet | 409 mit E01005, bedeutet Idempotenz-Schlüssel-Wiederverwendung. Korrigieren Sie den Schlüssel vor dem erneuten Versuch. |
| Eine andere Anfrage mit diesem Schlüssel läuft noch | 409 mit E01004, bedeutet Anfrage in Bearbeitung. Warten Sie kurz und versuchen Sie es erneut. |
| Schlüssel überschreitet 255 Zeichen | 422 mit E01001 bei Endpunkten, die den Header deklarieren. Kürzen Sie den Schlüssel. |
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.
Wenn die ursprüngliche Anfrage noch läuft, warten Sie, bevor Sie es erneut versuchen. Behalten Sie denselben Schlüssel und dieselbe Anfrage bei, damit der erneute Versuch die ursprüngliche Operation identifiziert.
Die API speichert eine 5xx-Antwort nicht als abgeschlossene Antwort. Versuchen Sie es nach einem Timeout oder Serverfehler mit begrenztem Backoff, demselben Schlüssel und einer identischen Anfrage innerhalb von drei Stunden erneut. Die Garantie der genau einmaligen Annahme gilt auch bei einer verlorenen Antwort.
Eine 4xx-Ablehnung kann gespeichert werden. Verwenden Sie für eine korrigierte Anfrage einen neuen Schlüssel: Ein unveränderter erneuter Versuch gibt eine gespeicherte Ablehnung erneut zurück, und eine geänderte Eingabe steht im Konflikt mit dem gespeicherten Schlüssel.
Warum erhalte ich denselben Webhook zweimal?
Bird kann die Zustellung eines Events, das Ihr Empfänger bereits gespeichert hat, erneut versuchen, wenn keine erfolgreiche Antwort eingeht.
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.
Jeder erneute Versuch behält denselben webhook-id-Header bei, der das Event identifiziert. Auch eine erneute Zustellung einer fehlgeschlagenen 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.
- Verifizieren Sie die Anfrage und fügen Sie dann deren Bezeichner und Job in derselben Transaktion ein.
- Geben Sie
2xxzurück, nachdem die Transaktion committed wurde, damit Bird die Wiederholungen einstellen kann. - 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.
Bei einem unterstützten HTTP-Schreibvorgang bindet Bird den Idempotenz-Schlüssel an den Workspace oder die Organisation der Anfrage. Unterstützte Staff-Operationen verwenden stattdessen das handelnde Staff-Konto. Wenn der Schutz nicht verfügbar ist, gibt Bird 503 E01033 IdempotencyUnavailable zurück, bevor dieser Versuch ausgeführt wird. Das klärt nicht das Ergebnis eines früheren Versuchs. Die Garantie der genau einmaligen Annahme gilt für übereinstimmende erneute Versuche innerhalb von drei Stunden. Prüfen Sie den Nachrichtenstatus, um die Zustellung zu bestätigen. Wenn die erneuten Versuche ausgeschöpft sind oder das Fenster abgelaufen ist, prüfen Sie das Ergebnis der ursprünglichen Operation, bevor Sie erneut senden.
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, wie Sie Anfragen an API erneut versuchen. Webhooks behandelt die separaten Zustellungsgarantien, die Ihr Empfänger handhabt.
Kurz gesagt
API-Wiederholungen und Webhook-Wiederholungen brauchen unterschiedliche Datensätze.
Verwenden Sie Idempotency-Key für eine Anfrage an Bird wieder. Ihr Empfänger speichert webhook-id, um ein bereits akzeptiertes Event zu erkennen.
Auch Ablehnungen können gespeichert werden.
Eine gespeicherte Ablehnung wird erneut zurückgegeben. Eine korrigierte Anfrage braucht einen neuen Schlüssel, weil sich ihre Eingabe unterscheidet.
Ein abgeschlossener Schlüssel kann nicht für andere Anfragen verwendet werden.
Ein geänderter JSON-Body oder -Endpunkt kann einen 409-Konflikt erzeugen. Korrigieren Sie den Schlüssel, statt den Konflikt unverändert erneut zu versuchen.
Deduplizierung hat Grenzen.
Die Garantie von API deckt die genau einmalige Annahme übereinstimmender erneuter Versuche innerhalb von drei Stunden ab. Ihr Webhook-Empfänger braucht eigene dauerhafte Event-Datensätze.