Réponse exemple
GET/v1/webhooks/deliveries/abandonedListe les livraisons de webhooks abandonnées (dead-letter queue) sur une fenêtre récente, regroupées par endpoint avec des actions recommandées.Cet endpoint expose la dead-letter queue des webhooks de votre espace de travail : les livraisons dont le statut est abandoned, c'est-à-dire celles qui ont épuisé la totalité de leur budget de réessais sans jamais réussir. Au-delà de la simple liste brute, la réponse regroupe les livraisons par webhook et calcule, pour chaque endpoint en souffrance, un compteur d'abandons et un bloc de `recommendations` suggérant les prochaines actions concrètes (désactiver, tester, rejouer la dernière livraison, consulter les métriques de santé). C'est l'outil de diagnostic à dégainer quand un endpoint cesse de répondre et accumule des échecs définitifs. L'endpoint est strictement limité à votre espace de travail (workspace_id) et trié des endpoints les plus touchés vers les moins touchés.
Authentification
Requiert une clé API valide portant le scope webhooks:read. Conformément à la hiérarchie de scopes, ce scope est aussi satisfait par webhooks:* (wildcard de ressource) ou par le wildcard global *. Une absence de ce scope renvoie une erreur 403 scope_missing. L'endpoint est classé expensive côté quota de débit (rate-limit), car il effectue un scan potentiellement large suivi d'une jointure de métadonnées.
Paramètres de requête
| Paramètre | Type | Requis | Description |
|---|---|---|---|
| days | integer (query) | Non | Taille de la fenêtre d'observation en jours, depuis maintenant. Défaut 7. Borné entre 1 et 30 (valeurs hors plage automatiquement ramenées dans cet intervalle ; valeur invalide → 7). |
| limit | integer (query) | Non | Nombre maximum de livraisons abandonnées retournées. Défaut 100. Borné entre 1 et 500 (valeur invalide → 100). |
Réponse
La réponse est un objet contenant object: "list", la fenêtre interrogée (range_days, since au format ISO 8601), le total total_abandoned, le tableau brut data des livraisons, et le tableau dérivé recommendations.
| Champ | Type | Description |
|---|---|---|
| range_days | integer | Fenêtre effectivement appliquée (après bornage du paramètre days). |
| since | string (ISO 8601) | Horodatage de début de la fenêtre, calculé comme maintenant moins range_days jours. |
| total_abandoned | integer | Nombre de livraisons abandonnées retournées dans data. |
| object | string | Toujours "list". |
| data[] | array | Livraisons abandonnées brutes, triées par created_at décroissant. |
| data[].id | string | Identifiant de la livraison (utilisable pour un rejeu). |
| data[].webhook_id | string | Identifiant du webhook destinataire. |
| data[].event_id / event_type | string | Événement à l'origine de la livraison (ex. transfer.completed). |
| data[].attempt_number / max_attempts | integer | Numéro de la dernière tentative et plafond de tentatives configuré. |
| data[].status_code | integer | null | Code HTTP renvoyé par l'endpoint à la dernière tentative (null si aucune réponse, ex. timeout). |
| data[].duration_ms | integer | Durée de la dernière tentative en millisecondes. |
| data[].error_message | string | null | Message d'erreur de la dernière tentative. |
| data[].created_at / completed_at | string (ISO 8601) | Création de la livraison et horodatage de l'abandon définitif. |
| recommendations[] | array | Un objet par webhook en souffrance, trié par abandoned_count décroissant. |
| recommendations[].webhook_name / webhook_url / webhook_active | string | null | boolean | Métadonnées hydratées du webhook ((deleted) / null / false si le webhook n'existe plus). |
| recommendations[].abandoned_count | integer | Nombre de livraisons abandonnées pour ce webhook dans la fenêtre. |
| recommendations[].latest_abandon_at | string (ISO 8601) | Abandon le plus récent pour ce webhook. |
| recommendations[].sample_delivery_id / sample_error | string | null | Identifiant et message de la livraison abandonnée la plus récente, à des fins de diagnostic. |
| recommendations[].suggested_next_actions | string[] | Actions recommandées (désactivation si ≥ 5 abandons, test de l'endpoint, métriques de santé, rejeu de la dernière livraison). |
Erreurs
| Code | Quand | Résolution |
|---|---|---|
| 401 missing_api_key | Aucun en-tête Authorization fourni (et pas de session valide). | Ajoutez Authorization: Bearer cof_live_.... |
| 401 invalid_api_key | Clé au préfixe non reconnu, introuvable ou invalide. | Vérifiez la clé ; régénérez-en une sur app.coffrify.com/developer. |
| 401 revoked_api_key | Clé révoquée ou inactive. | Utilisez une clé active. |
| 401 expired_api_key | Clé expirée. | Générez une nouvelle clé. |
| 403 scope_missing | La clé ne porte pas le scope webhooks:read (ni un scope plus large l'incluant). | Régénérez une clé avec le scope webhooks:read ou webhooks:*. |
| 403 ip_not_allowed | Adresse IP appelante hors de l'allow-list de la clé. | Appelez depuis une IP autorisée ou ajustez la liste. |
| 429 rate_limited | Quota de débit de l'espace de travail dépassé (endpoint classé expensive), ou max-uses de la clé atteint. | Respectez l'en-tête Retry-After puis réessayez. |
| 500 internal_error | Erreur serveur (ex. variables d'environnement Supabase manquantes). Une erreur sur la requête de livraisons retourne en revanche 200 avec data: [] et un champ note. | Réessayez ; si persistant, contactez le support avec le request_id. |
Voir aussi
- POST /v1/webhooks/deliveries/{delivery_id}/retry — rejouer une livraison abandonnée à partir de son
id. - POST /v1/webhooks/{id}/test — confirmer que l'endpoint est de nouveau joignable.
- GET /v1/webhooks/health — métriques de santé agrégées pour repérer un schéma de panne plus large.