Fehlgeschlagene Webhooks aus einer Dead-Letter-Queue erneut senden
Wenn Ihr Webhook-Endpoint während eines Deployments ausfällt, verwirft Keyright die Ereignisse nicht: Es wiederholt sie nach einem Backoff-Zeitplan, parkt die, die ihre Versuche aufbrauchen, in einer Dead-Letter-Queue und gibt Ihnen einen Admin-Endpoint zum Inspizieren und erneuten Senden. Hier sind die Zustandsmaschine der Zustellung, der Versuchsdatensatz und wie man ein geparktes Ereignis sicher erneut sendet, ohne die bereits angekommenen doppelt zu verarbeiten.
Ihr Abrechnungs-Reconciler lauscht auf license.revoked an einem Webhook-Endpoint. An einem Dienstag veröffentlichen Sie ein Deployment, der Endpoint liefert neunzig Sekunden lang 502, während die neuen Pods durchrollen, und in diesem Fenster lösen drei Erstattungen license.revoked aus. Würde der Lizenzdienst eine Fire-and-Forget-Zustellung verwenden, sind diese drei Ereignisse weg — und Ihr Zähler „aktiver Kunden” ist jetzt auf eine Weise falsch, die kein Wiederholungsversuch je korrigiert, weil nichts sich daran erinnert, dass die Ereignisse existierten. Der Ausfall waren neunzig Sekunden; die Datenabweichung ist dauerhaft.
Die Lösung besteht nicht darin, Ihren Endpoint perfekt zu machen. Sie besteht darin, die Zustellung dauerhaft zu machen: Jedes Ereignis wird vor dem Senden persistiert, bei Fehlschlag nach einem Zeitplan wiederholt und — erst wenn die Wiederholungen wirklich erschöpft sind — an einem Ort geparkt, wo Sie es wiederfinden und erneut senden können. Dieser Artikel behandelt die Produzentenseite der ausgehenden Webhooks von Keyright: die Zustellungs-Zustandsmaschine, den Wiederholungszeitplan, die Dead-Letter-Queue, die auffängt, was der Zeitplan nicht kann, und den Replay-Endpoint, mit dem Sie ein geparktes Ereignis erneut senden können, ohne die bereits angekommenen doppelt zu zählen.
Eine Zustellung ist ein Datensatz, kein Fire-and-Forget-Aufruf
Die Einheit, die Keyright verfolgt, ist nicht das Ereignis — es ist die Zustellung: ein Versuch, ein Ereignis an ein Abonnement zu senden. Wenn der ausstellende Dienst eine Zustandsänderung committet, schreibt er das Ereignis und, für jedes Abonnement, das zu diesem Ereignistyp passt, eine Zustellungszeile im Zustand pending. Der HTTP-POST erfolgt nach dem Commit, angetrieben von einem Worker, der diese Zeilen liest. Das ist die übliche Disziplin des Transactional-Outbox-Musters, und sie macht die Garantie ehrlich: Das Ereignis ist auf der Platte sicher, bevor irgendjemand verspricht, es zuzustellen, sodass ein Absturz zwischen „Commit” und „Senden” nichts verliert.
Jede Zustellung sammelt eine Historie, während der Worker sie abarbeitet:
{
"id": "whd_01JD9Q4ZB2K7M3X8V0",
"eventId": "evt_01JD9Q4ZB2K7M3X8V0",
"subscriptionId": "whs_7c1f9a",
"type": "license.revoked",
"status": "dead_lettered",
"attempts": 7,
"nextAttemptAt": null,
"attemptHistory": [
{ "at": "2026-11-17T14:02:11Z", "code": 502, "latencyMs": 1200, "error": "Bad Gateway" },
{ "at": "2026-11-17T14:02:26Z", "code": 502, "latencyMs": 1180, "error": "Bad Gateway" },
{ "at": "2026-11-17T14:03:11Z", "code": null, "latencyMs": 30000, "error": "timeout" }
]
}
Die attemptHistory ist der Teil, der seinen Platz verdient. Wenn eine Zustellung endgültig fehlschlägt, bekommen Sie nicht „es hat nicht funktioniert” — Sie bekommen den Statuscode und den Fehler jedes Versuchs, was Ihnen sofort sagt, ob das Problem Ihr Endpoint war (eine Serie von 502), ein Signaturfehler auf Ihrer Seite (eine Serie von 401, die Sie zurückgaben) oder ein langsamer Handler (timeout). Die Triage startet aus Beweisen, nicht aus einer Vermutung.
Der Wiederholungszeitplan
Eine Antwort, die kein 2xx ist, oder ein Verbindungsfehler lässt die Zustellung nicht scheitern — er plant den nächsten Versuch. Keyright verwendet exponentielles Backoff mit Jitter, sodass eine Flotte von Zustellungen an denselben sich erholenden Endpoint nicht im Gleichschritt wiederholt und ihn erneut umwirft. Der Zeitplan dehnt sich von Sekunden auf Stunden über eine begrenzte Versuchszahl:
Ein Deployment-Flackern von neunzig Sekunden fällt vollständig in die ersten zwei oder drei Versuche, sodass der kundenseitige Effekt null ist — das Ereignis landet ein paar Sekunden zu spät, und Sie hören nie davon. Der Zeitplan ist am Ende bewusst lang (Stunden, nicht Minuten), damit ein längerer Ausfall — ein fehlerhaftes Zertifikat, ein DNS-Fehler, ein Endpoint hinter einem Anbieter, dessen Wochenendwartung überzog — auf einem späteren Versuch dennoch gute Erfolgschancen hat, sobald Sie ihn beheben. Die Versuchszahl ist jedoch begrenzt. Ist sie aufgebraucht, hört die Zustellung auf zu wiederholen und geht zu dead_lettered über. Ewig zu wiederholen würde ein dauerhaft kaputtes Abonnement in einen unbegrenzten Rückstau verwandeln, der jedes gesunde aushungert.
Wenn die Versuche erschöpft sind: die Dead-Letter-Queue
dead_lettered ist ein terminaler, aber wiederherstellbarer Zustand. Die Zustellung wird nicht mehr automatisch wiederholt — nichts stößt sie von allein erneut an — aber sie wird nicht gelöscht. Sie liegt mit ihrer vollständigen Versuchshistorie in der Dead-Letter-Queue und wartet darauf, dass ein Mensch entscheidet, was zu tun ist. Listen Sie die Queue über die Admin-API auf:
GET /v1/admin/webhooks/deliveries?status=dead_lettered&subscription=whs_7c1f9a HTTP/1.1
Host: license.acme.example
Authorization: Bearer {admin_token}
oder von der CLI aus, wo der Großteil der Bereitschafts-Triage tatsächlich stattfindet:
$ keyright webhooks dlq list --subscription whs_7c1f9a
whd_01JD9Q4ZB2K7M3X8V0 license.revoked 7 attempts last 502 2026-11-17T14:03Z
whd_01JD9Q7PA1F2C9K4M0 license.renewed 7 attempts last 502 2026-11-17T14:03Z
whd_01JD9QB3X8V0M3K7J2 license.revoked 7 attempts last 502 2026-11-17T14:03Z
3 dead-lettered deliveries · oldest 2026-11-17T14:03Z
Drei Zustellungen, alle 502, alle datiert innerhalb Ihres Deployment-Fensters — die Queue hat Ihnen genau gesagt, was der Ausfall gekostet hat und welche Ereignisse erneut gesendet werden müssen. Die Dead-Letter-Queue erledigt hier zwei Aufgaben zugleich: Sie ist ein Sicherheitsnetz, das die Ereignisse bewahrt hat, und sie ist ein Vorfallsdatensatz, der den Wirkungsradius abgrenzt.
Eine geparkte Zustellung erneut senden
Das Replay stellt eine in der Dead-Letter-Queue liegende Zustellung als neue pending-Zustellung desselben Ereignisses erneut in die Warteschlange — selbe eventId, selbe Payload-Bytes, selbe Signatureingaben. Ihr Endpoint sieht genau das, was er beim ersten Versuch gesehen hätte:
# Eine Zustellung erneut senden...
$ keyright webhooks replay whd_01JD9Q4ZB2K7M3X8V0
whd_01JD9Q4ZB2K7M3X8V0 → re-enqueued as whd_01JDA2M5R0 (pending)
# ...oder jede in der Dead-Letter-Queue liegende Zustellung eines Abonnements, sobald der Endpoint gesund ist.
$ keyright webhooks dlq replay --subscription whs_7c1f9a --all
3 deliveries re-enqueued
Dieselbe Aktion ist ein Admin-Endpoint, den Ihre eigene Wiederherstellungsautomatisierung aufruft:
// Nachdem ein Health Check bestätigt, dass der Endpoint zurück ist, leere seine Dead-Letter-Queue.
async Task DrainDeadLetterQueueAsync(string subscriptionId, CancellationToken ct)
{
var parked = await _admin.ListDeliveriesAsync(
status: DeliveryStatus.DeadLettered,
subscription: subscriptionId,
ct: ct);
foreach (var delivery in parked)
{
// Das Replay bewahrt die ursprüngliche eventId, sodass ein Consumer, der nach
// eventId dedupliziert, ein bereits verarbeitetes Ereignis als harmloses No-op behandelt.
await _admin.ReplayDeliveryAsync(delivery.Id, ct);
}
}
Der Grund, warum ein Massen-Replay sicher ist, ohne zuerst herauszufinden, welches der drei Ereignisse Ihr Endpoint doch schließlich verarbeitet hat, ist, dass sich die event id beim Replay nicht ändert. Die Consumer-Seite ist bereits darauf gebaut, die mindestens-einmal-Zustellung zu überstehen — sie protokolliert jede verarbeitete eventId und ignoriert eine Wiederholung — sodass das erneute Senden der gesamten Queue aus Sicht des Empfängers idempotent ist. Eine Zustellung, die tatsächlich bei Versuch 6 ankam (und daher nie in die Dead-Letter-Queue wanderte), ist überhaupt nicht in der Queue; eine, die in die Dead-Letter-Queue wanderte, aber teilweise verarbeitet worden war, wird an ihrer id erkannt und übersprungen. Sie müssen bei der Grenze nicht präzise sein. Sie senden alles Geparkte erneut und lassen die Deduplizierung des Consumers es sortieren.
// Die Empfängerseite, die das blinde Replay sicher macht: Deduplizierung nach eventId.
app.MapPost("/webhooks/keyright", async (HttpRequest req, LedgerDb db) =>
{
var raw = await ReadRawBodyAsync(req);
if (!WebhookSignature.IsValid(req, raw, _secret))
return Results.Unauthorized();
var evt = JsonSerializer.Deserialize<WebhookEvent>(raw)!;
// Der erste Schreiber gewinnt; ein erneut gesendetes Duplikat kollidiert an der eindeutigen eventId und wird verworfen.
if (!await db.TryRecordProcessedAsync(evt.Id))
return Results.Ok(); // bereits verarbeitet — bestätigen und die Wiederholungen stoppen
await Reconcile(evt); // wende den in evt.Data getragenen Zustand an
return Results.Ok();
});
Wenn der Endpoint länger ausfällt als der Zeitplan
Der Wiederholungszeitplan und die Dead-Letter-Queue decken zusammen Ausfälle bis zum Aufbewahrungsfenster ab. Bei einem geplanten Ausfall, der länger dauert — eine Migration, eine mehrtägige Endpoint-Neufassung — lassen Sie die Ereignisse nicht ihre sieben Versuche gegen eine URL verbrennen, die Sie als tot kennen, und massenhaft in die Dead-Letter-Queue wandern. Pausieren Sie stattdessen das Abonnement:
$ keyright webhooks pause whs_7c1f9a --reason "endpoint migration"
subscription whs_7c1f9a paused — events held, not delivered
Ein pausiertes Abonnement protokolliert weiterhin jedes passende Ereignis, hält seine Zustellungen aber im Zustand pending zurück, ohne sie zu versuchen, sodass während Ihrer Arbeit nichts aus dem Aufbewahrungsfenster der Dead-Letter-Queue herausaltert. Wenn der neue Endpoint aktiv ist, gibt keyright webhooks resume whs_7c1f9a die zurückgehaltenen Zustellungen in den normalen Zeitplan frei. Das Pausieren tauscht Unmittelbarkeit bewusst gegen Dauerhaftigkeit; es ist das richtige Werkzeug, wenn Sie bereits wissen, dass der Endpoint weg ist.
Vorbehalte, die man klar aussprechen sollte
Das Replay stellt die Reihenfolge nicht wieder her. Erneut eingereihte Zustellungen laufen unabhängig durch den Zeitplan und können verschränkt ankommen. Wenn Ihr Handler relative Änderungen anwendet („einen Sitz abziehen”), beschädigt ein Replay in falscher Reihenfolge den Zähler. Tragen Sie den resultierenden Zustand im Payload — die neue Sitzsumme, das absolute expiresAt —, damit jedes Ereignis eine Momentaufnahme ist, die in beliebiger Reihenfolge sicher anwendbar ist, und gleichen Sie mit dem Lizenzdatensatz ab, wenn es das nicht ist.
Ein vergiftetes Ereignis wandert wegen Ihres Bugs in die Dead-Letter-Queue, nicht wegen eines Ausfalls. Wenn Ihr Handler bei einem bestimmten Payload eine Exception wirft, scheitert er an allen sieben Versuchen und parkt, genau wie ein ausgefallener Endpoint. Die Versuchshistorie klärt die Mehrdeutigkeit — ein 500, den Sie bei jedem Versuch zurückgaben, deutet auf Ihren Code, nicht auf das Netz — also lesen Sie sie, bevor Sie erneut senden, sonst parken Sie nur dasselbe Ereignis wieder.
Die Aufbewahrung ist begrenzt. Die Dead-Letter-Queue ist ein Wiederherstellungspuffer, kein Ereignisspeicher. Triagieren Sie sie innerhalb des Fensters; für eine langfristige Historie konsumieren Sie die license.*-Ereignisse in Ihr eigenes Audit-Log, während sie eintreffen, welches das maßgebliche System ist, das die Queue nie sein sollte.
Fazit
Dauerhafte Webhook-Zustellung besteht aus drei Mechanismen, die zusammenarbeiten. Der Wiederholungszeitplan fängt die kurzen Ausfälle ab, die 99 % der Realität ausmachen, sodass Sie sie nie bemerken. Die Dead-Letter-Queue fängt den langen Schwanz, den der Zeitplan nicht schlagen kann, und verwandelt ein verlorenes Ereignis in eine aufgelistete, inspizierbare Zeile mit ihrer vollständigen Fehlerhistorie. Der Replay-Endpoint sendet diese Zeilen mit ihren ursprünglichen event ids erneut, sodass ein Consumer, der nach event id dedupliziert, ein blindes Massen-Replay nehmen und konsistent herauskommen kann. Bauen Sie den Empfänger so, dass er dedupliziert und Zustands-Momentaufnahmen statt Deltas anwendet, und die Erholung von einem Endpoint-Ausfall hört auf, ein Daten-Reconciliation-Projekt zu sein, und wird zu einem einzigen Befehl: Queue auflisten, erneut senden, fertig.
Nebula.NET testen
Härten Sie Ihren .NET-Code in wenigen Minuten — starten Sie mit der kostenlosen Edition.