Ihr Empfänger kann ein Event speichern, auch wenn der Absender die Bestätigung nie erhält. Ein Wiederholungsversuch kann daher Arbeit wiederholen, die Ihre Anwendung bereits verarbeitet hat.
Wiederholungsversuche verzögern manche Events. Neuere Events können ankommen, bevor diese Wiederholungsversuche abgeschlossen sind. Speichern Sie Event-Kennungen und Auftretenszeiten, damit diese Zustellungen neuere Daten nicht überschreiben.
Was gilt als fehlgeschlagene Zustellung?
Bird behandelt eine Zustellung als fehlgeschlagen, wenn eine Nicht-Erfolgs-Antwort eingeht oder die Anfrage ein Timeout erreicht.
Geben Sie HTTP 2xx zurück, nachdem Sie das Event gespeichert haben, um Wiederholungsversuche für diese Zustellung zu stoppen. Ein Redirect, Client-Fehler oder Server-Fehler bleibt für erneute Versuche berechtigt.
Zum Beispiel protokolliert 400 eine abgelehnte Anfrage, weist Bird aber nicht an, sie zu verwerfen. Verwenden Sie eine Fehlerantwort, wenn die Signaturprüfung oder die dauerhafte Speicherung fehlschlägt, damit die Zustellung wiederhergestellt werden kann.
Speichern Sie das Event, bevor Sie es bestätigen. Zuerst eine Erfolgsantwort zu senden, kann das Event verlieren, wenn die anschließende Speicheroperation fehlschlägt.
Verlagern Sie langsame Verarbeitung in einen Hintergrund-Worker, damit Ihr Empfänger schnell antworten kann. Die Aufgabe des Empfängers ist es, das Event zu verifizieren und zu sichern, bevor diese Verarbeitung beginnt.
Wie sieht der Zeitplan für Wiederholungsversuche aus?
Bird verwendet sieben Wiederholungsintervalle nach dem ersten Versuch, insgesamt also acht Versuche.
| Versuch | Verzögerung nach dem vorherigen Versuch | Ungefähre verstrichene Zeit vor Zeitanpassungen |
|---|---|---|
| 1 | 5 Sekunden | 5 Sekunden |
| 2 | 5 Minuten | 5 Minuten 5 Sekunden |
| 3 | 30 Minuten | 35 Minuten 5 Sekunden |
| 4 | 2 Stunden | 2 Stunden 35 Minuten 5 Sekunden |
| 5 | 5 Stunden | 7 Stunden 35 Minuten 5 Sekunden |
| 6 | 10 Stunden | 17 Stunden 35 Minuten 5 Sekunden |
| 7 | 10 Stunden | 27 Stunden 35 Minuten 5 Sekunden |
Der Zeitplan gibt Ihnen etwa 27,5 Stunden, um einen Empfänger zu reparieren, bevor die automatischen Versuche enden.
Bird passt jede Wartezeit zufällig um bis zu 20 Prozent in beide Richtungen an, um Wiederholungsversuche nach einem Ausfall zu verteilen. Eine Fünf-Minuten-Verzögerung bewegt sich daher vor weiteren Anpassungen zwischen vier und sechs Minuten.
Eine Drosselungsantwort oder ein Timeout kann die nächste Wartezeit ändern. Bird berücksichtigt auch Retry-After, einen Antwort-Header, der eine Verzögerung vor dem nächsten Versuch anfordert. Betrachten Sie den Zeitplan als Wiederherstellungsfenster, nicht als exakte Frist.
Jeder Wiederholungsversuch behält die webhook-id des Events bei, sodass Ihr Empfänger Duplikate erkennen kann.
Was passiert nach dem letzten Wiederholungsversuch?
Automatische Wiederholungsversuche enden für diese Zustellung. Sie können ein Replay der fehlgeschlagenen Zustellungen anfordern.
Sie fordern eine erneute Zustellung mit createWebhookReplay oder über die Dashboard-Seite des Endpoints an. Replay liest das Zustellversuch-Protokoll und wählt die dort fehlgeschlagenen Events aus. Ein Event, das Bird nie versucht wurde – etwa weil es eintraf, während der Endpoint pausiert war –, hat keinen Versuch zum Auswählen, daher kann Replay es nicht wiederherstellen.
Die Antwort ist 202, d. h. das Replay wird zur Ausführung im Hintergrund eingereiht. Sie enthält weder eine Anzahl noch eine Aufgabenkennung. Verwenden Sie listWebhookAttempts, um nachfolgende Versuche zu prüfen.
Jede erneute Zustellung unternimmt einen einzigen Versuch statt der oben beschriebenen Abfolge. Bird protokolliert den Versuch und schließt den Vorgang ab, unabhängig davon, ob Ihr Empfänger ihn akzeptiert hat. Eine Wiedergabe an einen noch defekten Empfänger kostet daher eine Anfrage pro Ereignis statt acht. Reparieren Sie den Empfänger und starten Sie die Wiedergabe erneut. Diese Fehlschläge beeinflussen den Endpoint-Status nicht. Eine akzeptierte erneute Zustellung hebt die Degradierung auf.
Replay überspringt bereits erfolgreich bestätigte Zustellungen. Eine erneute Zustellung behält ihre ursprüngliche webhook-id, sodass Ihre Duplikaterkennung weiterhin greift.
Setzen Sie since und until als Datum-Uhrzeit-Strings, um das Wiederherstellungsfenster einzugrenzen. Beide Grenzen sind inklusiv. Beide beziehen sich auf den Zeitpunkt des Zustellversuchs, nicht auf den Zeitpunkt des Ereignisses. Ohne since beginnt das Fenster 24 Stunden vor der Anfrage – ein älterer Ausfall erfordert daher eine explizite Startzeit. Ohne until endet das Fenster zum Zeitpunkt der Anfrage.
Versuche werden drei Tage lang aufbewahrt – so weit reicht die Wiedergabe zurück. Ein früherer since vergrößert das Fenster, ohne ältere Ereignisse wiederherzustellen. Eine einzelne Wiedergabe umfasst außerdem höchstens die ältesten 10.000 Ereignisse im Fenster, sodass ein langer Ausfall mehrere schmalere Fenster erfordert.
Eine Organisation kann 20 Replays pro UTC-Tag anfordern. Ein weiterer Request erhält 429 mit WebhookReplayQuotaExceeded. Fassen Sie die Wiederherstellung daher in ein Fenster zusammen, statt Replay pro Event anzufordern.
Was passiert, wenn mein Endpoint dauerhaft fehlschlägt?
Bird stuft einen fehlschlagenden Endpoint als degradiert ein. Nach etwa fünf Tagen ununterbrochener Fehler wird die Zustellung pausiert.
Sie können seinen status als active, degraded oder paused lesen. Ein degradierter Endpoint empfängt weiterhin Zustellungen und Wiederholungsversuche. Eine erfolgreiche Zustellung hebt die Degradierung auf und setzt den Zähler für ununterbrochene Fehler zurück.
Ein pausierter Endpoint empfängt keine Events mehr und nimmt den Betrieb nicht automatisch wieder auf. Aktivieren Sie ihn mit updateWebhook erneut, indem Sie status auf active setzen. Starten Sie dann ein Replay für das Fenster, das die vor der Pause fehlgeschlagenen Zustellungen wiederherstellt. Aktivieren Sie zuerst: Ein Replay, das angefordert wird, während der Endpoint noch pausiert ist, gibt 202 zurück und stellt nichts erneut zu. Die schreibbaren Statuswerte sind active und paused.
Das Ändern der empfangenden url oder eine erfolgreiche Testzustellung hebt die Degradierung ebenfalls auf. Die Ersatz-URL muss öffentlich erreichbar sein (HTTPS), daher können private Adressen die Erreichbarkeit nicht wiederherstellen. URLs mit mehr als 2048 Zeichen bestehen die Validierung nicht – kürzen Sie eine generierte URL vor dem Absenden.
Das Bearbeiten der Beschreibung oder der Event-Abonnements des Endpoints weist nicht nach, dass er Requests empfangen kann. Diese Änderungen lassen die Degradierung bestehen, ebenso wie eine fehlgeschlagene Testzustellung.
Bird sendet den Inhabern der Organisation eine E-Mail, wenn ein Endpoint degradiert wird. Eine weitere Degradierungs-E-Mail wird erst gesendet, wenn der Endpoint sich erholt hat. Wiederholte Fehler erzeugen daher nicht bei jedem Versuch eine E-Mail. Ein Fehler nach der Erholung startet eine neue Degradierungsphase.
Gibt es eine Dead-Letter-Queue?
Bird stellt keine separate Warteschlange fehlgeschlagener Events zum Abrufen bereit. Prüfen Sie stattdessen Zustellversuche und fordern Sie Replay an.
| Wiederherstellungsaufgabe | Mechanismus |
|---|---|
| Fehler untersuchen | Zustellversuche protokollieren Ergebnis und Latenz jedes HTTP-Requests, neueste zuerst. |
| Wiederholte Zustellung an einen defekten Receiver stoppen | Pausieren nimmt den Endpoint aus der Zustellung. |
| Fehlgeschlagene Zustellungen wiederherstellen | Replay fordert eine erneute Zustellung innerhalb eines Zeitfensters an. |
Reparieren Sie den Receiver, aktivieren Sie ihn bei Bedarf erneut und starten Sie ein Replay für das betroffene Fenster. Es gibt keine separate Warteschlange, die anschließend abgearbeitet werden müsste.
Treffen Events in der richtigen Reihenfolge ein?
Events können in einer anderen Reihenfolge eintreffen als der, in der sie aufgetreten sind.
Ein email.delivered-Event kann vor dem email.accepted-Event derselben Nachricht eintreffen. Vergleichen Sie Event-Zeiten in timestamp, bevor Sie eine Änderung anwenden, die einen neueren Zustand überschreiben würde.
Verfolgen Sie jeden Teil einer SMS-Gebühr separat. Zum Beispiel sind die Zustellgebühr und eine Carrier-Gebühr separate Kostenkomponenten.
Das cost-Objekt ist null, bis eine Komponente bepreist wurde. Seine Komponentenwerte sind Dezimal-Strings oder null. Das Feld amount ist ein Dezimal-String, der die in diesem Payload vorhandenen Komponenten summiert.
Führen Sie jede Komponente anhand ihres neuesten Event-Zeitstempels zusammen. Das Ersetzen des gesamten Objekts kann eine Komponente löschen, die von einem anderen Event geliefert wurde, oder eine ältere Gebühr wiederherstellen.
Eine null-Komponente bedeutet, dass sie in diesem Payload nicht bepreist wurde. Sie bedeutet keine Gebühr von null. SMS-Events beschreibt dieses Zusammenführen im Kontext, und Webhooks behandelt die Zustellsemantik.
Kurz gesagt
Wiederholungsversuche folgen einem festen Zeitplan.
Acht Versuche erstrecken sich über etwa 27,5 Stunden vor Zeitanpassungen. Zufällige Änderungen der Wartezeiten verteilen Wiederholungsversuche, damit Empfänger keinem synchronisierten Ansturm ausgesetzt sind.
Bestätigen Sie erst nach dauerhafter Speicherung.
Eine 2xx-Antwort stoppt Wiederholungsversuche und schließt diese Zustellung vom Replay verpasster Events aus. Eine Fehlerantwort lässt sie für erneute Versuche berechtigt.
Ein pausierter Endpoint erfordert manuelle Wiederherstellung.
Aktivieren Sie ihn erneut und starten Sie dann ein Replay der Zustellungen, die vor der Pause fehlgeschlagen sind. Events, die während der Pause eintrafen, wurden nie versucht, daher kann Replay sie nicht erfassen.
Verwenden Sie die Event-Zeit für Aktualisierungen.
Die Zustellung ist ungeordnet. Vergleichen Sie Zeitstempel des Auftretens und führen Sie partielle SMS-Kosten pro Komponente zusammen.