Rechercher les livraisons de webhooks

Recherche transversale des livraisons de webhooks récentes du workspace, avec filtres par événement, statut, webhook et date.

2 min de lectureTélécharger en PDF

Réponse exemple

{
  "data": [
    {
      "id": "whd_3f9a1c4e2b",
      "status": "failed",
      "event_id": "evt_7c2f8a4d",
      "created_at": "2026-06-05T09:14:21.000Z",
      "event_type": "transfer.completed",
      "webhook_id": "wh_92ab17cd",
      "duration_ms": 842,
      "status_code": 500,
      "attempted_at": "2026-06-05T09:14:22.000Z",
      "completed_at": "2026-06-05T09:14:23.000Z",
      "max_attempts": 5,
      "error_message": "Endpoint returned HTTP 500",
      "next_retry_at": "2026-06-05T09:29:23.000Z",
      "attempt_number": 3
    },
    {
      "id": "whd_8b21d0f5a7",
      "status": "success",
      "event_id": "evt_55e1bb20",
      "created_at": "2026-06-05T08:02:09.000Z",
      "event_type": "document.signed",
      "webhook_id": "wh_92ab17cd",
      "duration_ms": 119,
      "status_code": 200,
      "attempted_at": "2026-06-05T08:02:10.000Z",
      "completed_at": "2026-06-05T08:02:10.000Z",
      "max_attempts": 5,
      "error_message": null,
      "next_retry_at": null,
      "attempt_number": 1
    }
  ],
  "filter": {
    "limit": 100,
    "since": "2026-06-01T00:00:00Z",
    "status": "failed",
    "event_id": null,
    "webhook_id": "wh_92ab17cd"
  },
  "object": "list"
}

GET/v1/webhooks/deliveries/searchRecherche transversale des tentatives de livraison de webhooks récentes du workspace.

Cet endpoint effectue une recherche transversale sur les tentatives de livraison de webhooks (coffrify_webhook_deliveries) de votre workspace, tous endpoints confondus. Contrairement à un listing rattaché à un seul webhook, il agrège les livraisons de tous vos webhooks et permet de les filtrer par événement, par statut, par webhook précis ou par date. Les résultats sont toujours triés du plus récent au plus ancien (created_at décroissant). C'est l'outil de référence pour déboguer une livraison qui a échoué ou pour retrouver toutes les tentatives liées à un événement donné.

Authentification

Cette requête nécessite une clé API valide disposant du scope webhooks:read. Le périmètre est automatiquement restreint au workspace associé à la clé : il est impossible de consulter les livraisons d'un autre workspace. Une clé sans ce scope reçoit une erreur 403 scope_missing.

Paramètres de requête

Tous les paramètres sont optionnels et se passent dans la query string. Ils se combinent en logique ET (chaque filtre fourni restreint davantage le résultat).

Paramètre	Type	Requis	Description
event_id	string	Non	Ne retourne que les livraisons rattachées à cet identifiant d'événement. Utile pour voir toutes les tentatives d'un même événement.
status	string	Non	Filtre par statut de livraison. Valeurs autorisées : `pending`, `success`, `failed`, `retrying`, `abandoned`. Toute autre valeur déclenche une erreur `400 validation_error`.
webhook_id	string	Non	Restreint la recherche aux livraisons d'un endpoint webhook précis.
since	string	Non	Borne basse de date (ISO 8601). Ne retourne que les livraisons dont `created_at` est supérieur ou égal à cette valeur.
limit	integer	Non	Nombre maximum de livraisons retournées. Par défaut 100, borné entre 1 et 500 (les valeurs hors bornes sont automatiquement ramenées dans l'intervalle).

Réponse

La réponse est un objet de type liste : object vaut "list", data contient le tableau des livraisons et filter rappelle les filtres effectivement appliqués (y compris la valeur de limit retenue). Chaque élément de data expose : id, webhook_id, event_id, event_type, status, status_code (code HTTP renvoyé par votre endpoint), attempt_number et max_attempts (compteur de tentatives), duration_ms (latence de l'appel), error_message (raison de l'échec le cas échéant), ainsi que les horodatages attempted_at, completed_at, next_retry_at et created_at.

Le champ next_retry_at n'est renseigné que pour une livraison en attente de nouvelle tentative (retrying) ; il vaut null pour les livraisons terminées (success, failed, abandoned).

Erreurs

Code	Quand	Résolution
400 validation_error	Le paramètre `status` n'est pas l'une des valeurs autorisées.	Utilisez l'une des valeurs : pending, success, failed, retrying, abandoned.
401 missing_api_key	Aucune clé API n'est fournie dans l'en-tête Authorization.	Ajoutez l'en-tête `Authorization: Bearer <clé>`.
401 invalid_api_key	La clé API est invalide, révoquée ou expirée.	Vérifiez la clé ou générez-en une nouvelle depuis la console.
403 scope_missing	La clé n'a pas le scope `webhooks:read`.	Émettez une clé incluant le scope `webhooks:read`.
429 rate_limited	Quota de requêtes du workspace dépassé sur les endpoints en lecture.	Respectez l'en-tête `Retry-After` puis réessayez.
500 internal_error	Erreur côté base de données lors de la requête.	Réessayez ; si le problème persiste, contactez le support avec le `request_id`.

Voir aussi

GET /v1/webhooks — lister les endpoints webhook configurés du workspace.
POST /v1/webhooks/{id}/rotate-secret — faire tourner le secret de signature d'un webhook.
GET /v1/events — consulter les événements à l'origine des livraisons.