Comprendre la stratégie de retry et configurer le back-off

Chaque fois que Coffrify déclenche un Webhook, une ligne est créée dans la table coffrify_webhook_deliveries. Si votre serveur répond avec un code HTTP hors de la plage 2xx (ou si la connexion expire après 10 secondes), la livraison passe en statut retrying et sera re-tentée jusqu'à un maximum de 10 tentatives. Une fois ce budget épuisé, la livraison bascule en abandoned et rejoint la file des livraisons mortes. Deux endpoints vous permettent de piloter ce cycle de vie : la liste des livraisons d'un Webhook donné et la recherche transversale sur tout le workspace.

Authentification

Ces trois endpoints nécessitent une clé API valide (préfixe cof_live_…, cof_test_… ou cof_sandbox_…) passée dans l'en-tête Authorization: Bearer <clé>. La lecture des livraisons requiert le scope webhooks:read. Le déclenchement d'un retry ou d'un replay nécessite le scope webhooks:manage, qui inclut les droits d'écriture sur les Webhooks du workspace.

Paramètres de requête disponibles

Les endpoints de listing et de recherche acceptent des filtres (statut, événement, webhook, date) et la pagination. Le tableau ci-dessous les détaille par endpoint.

Exemples d'appel

Les exemples ci-dessous listent les livraisons d'un webhook, en recherchent les échecs, puis en rejouent une. Choisissez votre langage.

# Lister les 20 dernières livraisons d'un Webhook
curl -G https://api.coffrify.com/v1/webhooks/wh_abc123/deliveries \
  -H "Authorization: Bearer cof_live_xxxxx" \
  -d limit=20 \
  -d offset=0
 
# Rechercher toutes les livraisons en statut 'failed' depuis 24 h
curl -G https://api.coffrify.com/v1/webhooks/deliveries/search \
  -H "Authorization: Bearer cof_live_xxxxx" \
  -d status=failed \
  -d since=$(date -u -v-1d +"%Y-%m-%dT%H:%M:%SZ")
 
# Forcer le retry d'une livraison abandonnée
curl -X POST https://api.coffrify.com/v1/webhooks/deliveries/del_xyz789/retry \
  -H "Authorization: Bearer cof_live_xxxxx"

Réponses

Voici les formes de réponse réelles retournées par chaque endpoint, basées sur les champs sélectionnés dans les handlers.

// GET /v1/webhooks/{id}/deliveries
{
  "object": "list",
  "total": 42,
  "has_more": true,
  "data": [
    {
      "id": "del_01hwxyz",
      "event_id": "evt_01abc",
      "event_type": "transfer.downloaded",
      "attempt_number": 3,
      "max_attempts": 10,
      "status": "retrying",
      "status_code": 503,
      "duration_ms": 4231,
      "error_message": "Service Unavailable",
      "attempted_at": "2026-06-06T08:12:00.000Z",
      "completed_at": null,
      "next_retry_at": "2026-06-06T08:27:00.000Z",
      "created_at": "2026-06-06T08:00:00.000Z"
    }
  ]
}

// GET /v1/webhooks/deliveries/search
{
  "object": "list",
  "data": [ /* mêmes champs que ci-dessus + webhook_id */ ],
  "filter": {
    "event_id": null,
    "status": "failed",
    "webhook_id": null,
    "since": "2026-06-05T00:00:00.000Z",
    "limit": 100
  }
}
 
// POST /v1/webhooks/deliveries/{id}/retry
{
  "id": "del_01hwxyz",
  "status": "pending",
  "next_retry_at": "2026-06-06T09:05:22.000Z",
  "attempt_number": 0,
  "max_attempts": 10,
  "queued_for_retry": true
}

Cycle de vie d'une livraison

Une livraison passe par plusieurs statuts (en attente, livrée, en échec, abandonnée). La liste ci-dessous décrit chaque étape et les transitions de retry automatique.

1. pending : la livraison vient d'être créée, en attente d'exécution par le cron.
2. retrying : au moins une tentative a échoué (code non-2xx ou timeout 10 s), next_retry_at indique la prochaine tentative.
3. success : le serveur de destination a répondu avec un code 2xx. Aucune nouvelle tentative n'est effectuée.
4. failed : toutes les tentatives ont été effectuées sans succès, mais le budget n'est pas encore épuisé.
5. abandoned : le quota de max_attempts (10) est atteint. La livraison entre dans la file morte consultable via /v1/webhooks/deliveries/abandoned.

Erreurs

Les erreurs portent sur un webhook ou une livraison introuvable, ou un scope manquant. Le tableau ci-dessous indique la résolution.

Bonnes pratiques

Voir aussi

• Créer et gérer vos Webhooks
• Vérifier la signature HMAC d'un Webhook
• Rejouer une livraison manuellement
• File des livraisons abandonnées
• Référence endpoint : GET /v1/webhooks/{id}/deliveries
• Référence endpoint : GET /v1/webhooks/deliveries/search