Skip to content
← Tous les articles
· Delta1 Labs WebhooksKeyright

Rejouer les webhooks échoués depuis une file de rebut

Quand votre endpoint de webhooks tombe pendant un déploiement, Keyright ne jette pas les événements : il les réessaie selon un calendrier de backoff, gare dans une file de rebut ceux qui épuisent leurs tentatives, et vous donne un endpoint d'administration pour les inspecter et les rejouer. Voici la machine à états de livraison, l'enregistrement des tentatives, et comment réémettre un événement garé sans traiter deux fois ceux déjà arrivés.

Votre réconciliateur de facturation écoute license.revoked sur un endpoint de webhooks. Un mardi, vous publiez un déploiement, l’endpoint renvoie des 502 pendant quatre-vingt-dix secondes le temps que les nouveaux pods basculent, et dans cette fenêtre trois remboursements déclenchent license.revoked. Si le service de licences utilisait une livraison sans garantie, ces trois événements sont perdus — et votre décompte de « clients actifs » est désormais faux d’une manière qu’aucun réessai ne corrigera jamais, parce que rien ne se souvient que les événements ont existé. La panne a duré quatre-vingt-dix secondes ; la dérive des données est permanente.

La solution n’est pas de rendre votre endpoint parfait. C’est de rendre la livraison durable : chaque événement est persisté avant d’être envoyé, réessayé selon un calendrier en cas d’échec, et — seulement quand les réessais sont réellement épuisés — garé quelque part où vous pouvez le retrouver et le renvoyer. Cet article traite du côté producteur des webhooks sortants de Keyright : la machine à états de livraison, le calendrier de réessais, la file de rebut qui attrape ce que le calendrier ne peut pas, et l’endpoint de rejeu qui vous laisse réémettre un événement garé sans compter deux fois ceux déjà arrivés.

Une livraison est un enregistrement, pas un appel à l’aveugle

L’unité que Keyright suit n’est pas l’événement — c’est la livraison : une tentative d’envoyer un événement à un abonnement. Quand le service émetteur valide un changement d’état, il écrit l’événement et, pour chaque abonnement correspondant à ce type d’événement, une ligne de livraison à l’état pending. Le POST HTTP a lieu après la validation, piloté par un worker qui lit ces lignes. C’est la discipline habituelle du pattern outbox transactionnel, et c’est ce qui rend la garantie honnête : l’événement est à l’abri sur disque avant que quiconque promette de le livrer, donc un crash entre « valider » et « envoyer » ne perd rien.

Chaque livraison accumule un historique à mesure que le worker la traite :

{
  "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" }
  ]
}

L’attemptHistory est la partie qui justifie sa place. Quand une livraison échoue définitivement, vous n’obtenez pas « ça n’a pas marché » — vous obtenez le code de statut et l’erreur de chaque tentative, ce qui vous dit instantanément si le problème venait de votre endpoint (une série de 502), d’une signature invalide de votre côté (une série de 401 que vous avez renvoyés) ou d’un handler lent (timeout). Le tri part de la preuve, pas d’une supposition.

Le calendrier de réessais

Une réponse autre que 2xx ou un échec de connexion ne condamne pas la livraison — elle programme la tentative suivante. Keyright utilise un backoff exponentiel avec jitter, de sorte qu’une flotte de livraisons vers le même endpoint en reprise ne réessaie pas à l’unisson et ne le refait pas tomber. Le calendrier s’étire de secondes à heures sur un nombre borné de tentatives :

pending delivering delivered retrying dead_lettered 2xx timeout / non-2xx backoff écoulé · tentatives restantes tentatives épuisées rejeu — remise en file même event id Tentative 1 immédiate · 2 à ~15s · 3 à ~1m · 4 à ~5m · 5 à ~30m · 6 à ~2h · 7 à ~6h, puis rebut

Un clignotement de déploiement de quatre-vingt-dix secondes tombe entièrement dans les deux ou trois premières tentatives, donc l’effet côté client est nul — l’événement arrive quelques secondes en retard et vous n’en entendez jamais parler. Le calendrier est délibérément long sur la queue (des heures, pas des minutes) pour qu’une panne plus longue — un certificat défectueux, une erreur DNS, un endpoint derrière un fournisseur dont la maintenance de week-end a débordé — ait quand même de bonnes chances de réussir sur une tentative ultérieure une fois que vous l’avez corrigée. Le nombre de tentatives, lui, est borné. Quand il est épuisé, la livraison cesse de réessayer et passe à dead_lettered. Réessayer indéfiniment transformerait un abonnement cassé en permanence en un backlog illimité qui affamerait tous les sains.

Quand les tentatives sont épuisées : la file de rebut

dead_lettered est un état terminal mais récupérable. La livraison n’est plus réessayée automatiquement — rien ne la poussera de nouveau tout seul — mais elle n’est pas supprimée. Elle reste dans la file de rebut avec son historique complet de tentatives, en attendant qu’une personne décide quoi faire. Listez la file via l’API d’administration :

GET /v1/admin/webhooks/deliveries?status=dead_lettered&subscription=whs_7c1f9a HTTP/1.1
Host: license.acme.example
Authorization: Bearer {admin_token}

ou depuis la CLI, qui est l’endroit où se fait réellement l’essentiel du tri d’astreinte :

$ 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

Trois livraisons, toutes 502, toutes datées dans votre fenêtre de déploiement — la file vous a dit exactement ce que la panne a coûté et quels événements doivent être réémis. La file de rebut fait deux travaux à la fois ici : c’est un filet de sécurité qui a conservé les événements, et c’est un enregistrement d’incident qui borne le rayon d’impact.

Rejouer une livraison garée

Le rejeu remet en file une livraison en rebut comme une nouvelle livraison pending du même événement — même eventId, mêmes octets de payload, mêmes entrées de signature. Votre endpoint voit exactement ce qu’il aurait vu à la première tentative :

# Réémettre une livraison...
$ keyright webhooks replay whd_01JD9Q4ZB2K7M3X8V0
whd_01JD9Q4ZB2K7M3X8V0 → re-enqueued as whd_01JDA2M5R0 (pending)

# ...ou chaque livraison en rebut d'un abonnement, une fois l'endpoint sain.
$ keyright webhooks dlq replay --subscription whs_7c1f9a --all
3 deliveries re-enqueued

La même action est un endpoint d’administration, c’est ce qu’appelle votre propre automatisation de reprise :

// Après un health check confirmant que l'endpoint est revenu, vide sa file de rebut.
async Task DrainDeadLetterQueueAsync(string subscriptionId, CancellationToken ct)
{
    var parked = await _admin.ListDeliveriesAsync(
        status: DeliveryStatus.DeadLettered,
        subscription: subscriptionId,
        ct: ct);

    foreach (var delivery in parked)
    {
        // Le rejeu préserve l'eventId d'origine, donc un consommateur qui déduplique
        // sur eventId traite un événement déjà traité comme une opération nulle inoffensive.
        await _admin.ReplayDeliveryAsync(delivery.Id, ct);
    }
}

La raison pour laquelle un rejeu en masse est sûr sans déterminer d’abord lequel des trois événements votre endpoint a finalement traité, c’est que l’event id ne change pas au rejeu. Le côté consommateur est déjà construit pour survivre à la livraison au moins une fois — il enregistre chaque eventId qu’il a traité et ignore une répétition — donc réémettre toute la file est idempotent du point de vue du récepteur. Une livraison qui est réellement arrivée à la tentative 6 (et n’est donc jamais partie en rebut) n’est pas du tout dans la file ; une qui est partie en rebut mais avait été partiellement traitée est reconnue par son id et écartée. Vous n’avez pas à être précis sur la frontière. Vous rejouez tout ce qui s’est garé et laissez la déduplication du consommateur faire le tri.

// Le côté récepteur qui rend le rejeu à l'aveugle sûr : déduplication sur 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)!;

    // Le premier à écrire gagne ; un doublon rejoué entre en collision sur l'eventId unique et est écarté.
    if (!await db.TryRecordProcessedAsync(evt.Id))
        return Results.Ok();      // déjà traité — acquitte et arrête les réessais

    await Reconcile(evt);         // applique l'état porté par evt.Data
    return Results.Ok();
});

Quand l’endpoint sera hors service plus longtemps que le calendrier

Le calendrier de réessais et la file de rebut couvrent ensemble les pannes jusqu’à la fenêtre de rétention. Pour une panne planifiée plus longue que cela — une migration, une réécriture d’endpoint sur plusieurs jours — ne laissez pas les événements brûler leurs sept tentatives contre une URL que vous savez morte et partir en rebut en masse. Mettez l’abonnement en pause à la place :

$ keyright webhooks pause whs_7c1f9a --reason "endpoint migration"
subscription whs_7c1f9a paused — events held, not delivered

Un abonnement en pause enregistre toujours chaque événement correspondant mais retient ses livraisons à l’état pending sans les tenter, de sorte que rien ne vieillit hors de la fenêtre de rétention du rebut pendant que vous travaillez. Quand le nouvel endpoint est actif, keyright webhooks resume whs_7c1f9a libère les livraisons retenues dans le calendrier normal. La pause échange l’immédiateté contre la durabilité délibérément ; c’est le bon outil quand vous savez déjà que l’endpoint est parti.

Mises en garde à énoncer clairement

Le rejeu ne restaure pas l’ordre. Les livraisons remises en file courent dans le calendrier indépendamment et peuvent arriver entrelacées. Si votre handler applique des changements relatifs (« retire un siège »), un rejeu dans le désordre corrompt le décompte. Portez l’état résultant dans le payload — le nouveau total de sièges, l’expiresAt absolu — pour que chaque événement soit un instantané sûr à appliquer dans n’importe quel ordre, et réconciliez avec l’enregistrement de licence quand ce n’est pas le cas.

Un événement empoisonné part en rebut à cause de votre bug, pas d’une panne. Si votre handler lève une exception sur un payload précis, il échouera aux sept tentatives et se garera, exactement comme un endpoint hors service. L’historique des tentatives lève l’ambiguïté — un 500 que vous avez renvoyé à chaque tentative pointe vers votre code, pas vers le réseau — alors lisez-le avant de rejouer, sinon vous ne ferez que regarer le même événement.

La rétention est bornée. La file de rebut est un tampon de reprise, pas un magasin d’événements. Triez-la dans la fenêtre ; pour un historique à long terme, consommez les événements license.* dans votre propre journal d’audit à mesure qu’ils arrivent, qui est le système de référence que la file n’a jamais prétendu être.

À retenir

La livraison durable de webhooks, ce sont trois mécanismes qui travaillent ensemble. Le calendrier de réessais absorbe les courtes pannes qui sont 99 % de la réalité, donc vous ne les remarquez jamais. La file de rebut attrape la longue queue que le calendrier ne peut pas battre et transforme un événement perdu en une ligne listée et inspectable avec son historique complet d’échecs. L’endpoint de rejeu réémet ces lignes avec leurs event ids d’origine, donc un consommateur qui déduplique sur l’event id peut prendre un rejeu en masse à l’aveugle et en ressortir cohérent. Construisez le récepteur pour qu’il déduplique et applique des instantanés d’état plutôt que des deltas, et se remettre d’une panne d’endpoint cesse d’être un projet de réconciliation de données pour devenir une seule commande : listez la file, rejouez-la, terminé.

Essayez Nebula.NET

Renforcez votre code .NET en quelques minutes — commencez avec l'édition gratuite.