Réessais et file morte

Coffrify livre chaque évènement à votre endpoint en attendant une réponse HTTP 2xx. Quand l'endpoint répond par un code non-2xx ou ne répond pas à temps, la livraison n'est pas perdue : elle est réessayée automatiquement avec un délai croissant, puis, si le budget de réessais est épuisé, déplacée dans une file morte que vous pouvez consulter et rejouer. Cette page explique le cycle de vie d'une livraison, comment inspecter les échecs, comment relancer une livraison à la main, et comment réagir à la désactivation automatique d'un endpoint qui ne répond plus.

Cycle de vie d'une livraison

Chaque tentative d'envoi vers votre endpoint est enregistrée comme une livraison (delivery). Une livraison porte un statut qui évolue au fil des tentatives. Vous retrouvez ces statuts dans l'historique de chaque webhook et dans la file morte.

Une livraison est considérée comme réussie dès que votre endpoint renvoie un code dans la plage 200 à 299. Tout autre code, ou une absence de réponse dans le délai imparti, compte comme un échec et déclenche le mécanisme de réessai.

Backoff exponentiel

Quand une tentative échoue, Coffrify ne réessaie pas immédiatement : le délai entre deux tentatives croît à chaque échec (backoff exponentiel). Cela laisse à votre service le temps de se rétablir et évite d'aggraver une panne par une rafale de requêtes. Le moment de la prochaine tentative est exposé dans le champ next_retry_at de la livraison. Le budget total est de 10 tentatives par livraison (champ max_attempts), après quoi la livraison passe en abandoned.

Idempotence : dédupliquez via webhook-id

Parce que les livraisons sont réessayées, votre endpoint peut recevoir le même évènement plusieurs fois. C'est inhérent à toute livraison « au moins une fois » : un réessai après un timeout réseau peut arriver alors que la première requête avait en réalité abouti chez vous. Vous devez donc traiter les livraisons de façon idempotente.

Chaque livraison transporte l'en-tête webhook-id, identifiant unique et stable de l'évènement. Lors d'un réessai ou d'un rejeu, ce webhook-id ne change pas. Stockez-le et ignorez tout évènement dont le webhook-id a déjà été traité.

// Express : dédupliquer sur webhook-id avant tout traitement
app.post('/webhooks/coffrify', async (req, res) => {
  const id = req.get('webhook-id');
 
  // 1) Vérifiez la signature (voir la doc Signatures), puis :
  const fresh = await store.markSeen(id); // INSERT ... ON CONFLICT DO NOTHING
  if (!fresh) {
    // Déjà traité : accusez réception sans rejouer l'effet de bord.
    return res.sendStatus(200);
  }
 
  // 2) Répondez immédiatement, traitez en tâche de fond.
  res.sendStatus(200);
  queue.enqueue(req.body);
});

Inspecter les livraisons d'un webhook

Pour comprendre pourquoi un endpoint échoue, listez ses livraisons récentes. Chaque entrée indique le statut, le code HTTP renvoyé (status_code), la durée, le numéro de tentative et un éventuel message d'erreur.

$ curl -s https://api.coffrify.com/v1/webhooks/wh_3aF9.../deliveries?limit=20 \
    -H "Authorization: Bearer cof_live_..."
 
{
  "object": "list",
  "data": [
    {
      "id": "whd_7Qm2...",
      "event_type": "transfer.downloaded",
      "status": "failed",
      "status_code": 502,
      "attempt_number": 4,
      "max_attempts": 10,
      "next_retry_at": "2026-06-10T14:32:00Z",
      "error_message": "Bad Gateway"
    }
  ],
  "has_more": false,
  "total": 1
}

Cet endpoint accepte les paramètres limit (100 au maximum) et offset pour la pagination, et renvoie has_more ainsi que total. Pour obtenir le détail complet d'une livraison, charge utile et corps de réponse de votre serveur compris, interrogez-la par son identifiant.

File morte : les livraisons abandonnées

Une livraison qui a épuisé ses réessais passe au statut abandoned. Elle n'est pas supprimée : elle reste consultable dans la file morte (dead-letter queue), de sorte qu'aucun évènement n'est définitivement perdu sans que vous puissiez le constater et le rejouer.

Le paramètre days fixe la fenêtre d'observation, de 1 à 30 jours (7 par jour défaut). La réponse regroupe les abandons par endpoint et propose des actions recommandées pour chacun, ce qui vous aide à décider s'il faut relancer, rejouer ou désactiver le webhook fautif.

$ curl -s "https://api.coffrify.com/v1/webhooks/deliveries/abandoned?days=7" \
    -H "Authorization: Bearer cof_live_..."
 
{
  "range_days": 7,
  "total_abandoned": 12,
  "object": "list",
  "data": [ /* livraisons abandonnées */ ],
  "recommendations": [
    {
      "webhook_id": "wh_3aF9...",
      "webhook_url": "https://exemple.com/hook",
      "abandoned_count": 12,
      "sample_error": "Bad Gateway"
    }
  ]
}

Relancer : retry et replay

Deux endpoints permettent de renvoyer une livraison, avec des usages distincts. Tous deux exigent le scope webhooks:manage.

retry s'applique à une livraison qui n'a pas réussi (failed ou abandoned) : il réinitialise son compteur de tentatives et la replanifie immédiatement, le mécanisme de réessai reprenant ensuite la main. Si la livraison avait déjà réussi, l'appel renvoie une erreur 409 ; utilisez alors replay pour renvoyer quand même.

replay envoie tout de suite la livraison vers l'URL du webhook et crée une nouvelle entrée dans l'historique. L'identifiant d'évènement d'origine est préservé, donc votre endpoint reçoit le même webhook-id et votre déduplication s'applique. Le webhook doit être actif : s'il a été désactivé, replay renvoie une erreur 409, réactivez-le d'abord.

$ curl -s -X POST \
    https://api.coffrify.com/v1/webhooks/deliveries/whd_7Qm2.../retry \
    -H "Authorization: Bearer cof_live_..." \
    -H "Idempotency-Key: retry-whd_7Qm2-2026-06-10"
 
{ "id": "whd_7Qm2...", "status": "pending", "queued_for_retry": true }

Désactivation automatique de l'endpoint

Quand un endpoint échoue de façon répétée, Coffrify finit par le désactiver automatiquement pour cesser d'envoyer dans le vide. Deux évènements de la famille webhook vous le signalent, à condition d'y être abonné sur un autre endpoint sain ou de surveiller votre journal.

Un webhook désactivé ne reçoit plus aucun évènement tant qu'il n'est pas réactivé. Après avoir corrigé votre service, réactivez l'endpoint puis rejouez les livraisons restées dans la file morte. La marche à suivre type est la suivante.

1. Diagnostiquez avec GET /v1/webhooks/deliveries/abandoned et GET /v1/webhooks/health (taux de succès, latence p95).
2. Corrigez votre endpoint et confirmez qu'il est joignable avec POST /v1/webhooks/{id}/test.
3. Réactivez l'endpoint via PATCH /v1/webhooks en passant { "id": "wh_...", "is_active": true }.
4. Rejouez les livraisons abandonnées avec POST /v1/webhooks/deliveries/{id}/retry (ou /replay).
5. Vérifiez qu'aucune nouvelle abandonnée n'apparaît dans la fenêtre suivante.

Surveiller la santé des livraisons

Pour anticiper plutôt que subir, suivez régulièrement les taux de succès et la latence de vos endpoints. L'endpoint de santé agrège, par webhook, le nombre de livraisons en succès, échec, réessai et abandon, ainsi que les latences p50, p95 et p99 sur la fenêtre demandée.

Le paramètre hours fixe la fenêtre, jusqu'à 168 heures (7 jours). Chaque endpoint reçoit un indicateur health : healthy au-dessus de 95 pour cent de succès, degraded entre 50 et 95 pour cent, critical en dessous. Pour rechercher des livraisons à travers tous vos webhooks, par exemple toutes les abandoned d'un même event_id, utilisez GET /v1/webhooks/deliveries/search avec les filtres event_id, status, webhook_id et since.