Endpoint : Webhooks

Créez, listez, modifiez, supprimez et testez vos webhooks Coffrify, et explorez le catalogue public des types d'événements.

Les webhooks permettent à Coffrify d'appeler votre serveur en temps réel quand un événement se produit dans votre espace : un transfert téléchargé, un document reçu, un coffre consulté, un export RGPD demandé. Vous enregistrez une URL HTTPS et une liste d'événements à écouter ; Coffrify y envoie ensuite une requête POST signée à chaque déclenchement. Cette page décrit l'endpoint de gestion des webhooks : création, liste, modification, suppression, envoi de test, et exploration du catalogue d'événements. Toutes les requêtes utilisent la base https://api.coffrify.com/v1 et l'en-tête Authorization: Bearer <clé>.

Créer un webhook

POST/v1/webhooksEnregistre un nouveau webhook. Scope webhooks:manage. Le secret de signature n'est renvoyé qu'à cette occasion.

Le corps accepte name (obligatoire), url (obligatoire, doit être une URL valide), events (tableau de types d'événements) et description (facultatif). Si vous omettez events ou envoyez un tableau vide, Coffrify écoute par défaut transfer.downloaded. Chaque type fourni est validé contre le catalogue : un type inconnu renvoie une erreur validation_error listant les valeurs invalides. Comme cet appel modifie l'état, vous pouvez ajouter l'en-tête Idempotency-Key (8 à 255 caractères) pour le rendre rejouable sans créer de doublon.

curl -X POST https://api.coffrify.com/v1/webhooks \
  -H "Authorization: Bearer cof_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wh-create-2026-06-10-a1" \
  -d '{
    "name": "Notifications production",
    "url": "https://exemple.fr/webhooks/coffrify",
    "events": ["transfer.downloaded", "transfer.expired", "request.submitted"],
    "description": "Alimente notre file de traitement interne"
  }'

La réponse renvoie le webhook créé avec un statut 201. Le champ secret (préfixe whsec_) sert à vérifier la signature des livraisons : il n'est retourné qu'à la création et n'apparaît dans aucune lecture ultérieure. Stockez-le immédiatement dans un coffre à secrets. Le champ signing_version vaut v1, et le webhook est actif (is_active: true) dès sa création.

{
  "id": "wh_2bX9...",
  "name": "Notifications production",
  "description": "Alimente notre file de traitement interne",
  "url": "https://exemple.fr/webhooks/coffrify",
  "events": ["transfer.downloaded", "transfer.expired", "request.submitted"],
  "is_active": true,
  "signing_version": "v1",
  "created_at": "2026-06-10T09:30:00.000Z",
  "secret": "whsec_..."
}

Lister les webhooks

GET/v1/webhooksRenvoie tous les webhooks de l'espace, du plus récent au plus ancien. Scope webhooks:read.

La liste expose pour chaque webhook ses métadonnées et ses compteurs de fiabilité : success_count, failure_count, last_triggered_at et last_status. Le secret n'est jamais inclus. Les webhooks de l'environnement bac à sable (clés cof_sandbox_) sont isolés : une clé sandbox ne voit que les webhooks sandbox, et les clés live ou test ne voient jamais ceux du bac à sable.

$ curl https://api.coffrify.com/v1/webhooks \
    -H "Authorization: Bearer cof_live_..."

{
  "object": "list",
  "data": [
    {
      "id": "wh_2bX9...",
      "name": "Notifications production",
      "url": "https://exemple.fr/webhooks/coffrify",
      "events": ["transfer.downloaded", "transfer.expired"],
      "is_active": true,
      "signing_version": "v1",
      "success_count": 142,
      "failure_count": 0,
      "last_triggered_at": "2026-06-10T08:55:11.000Z",
      "last_status": 200,
      "created_at": "2026-06-01T10:00:00.000Z"
    }
  ]
}

Modifier un webhook

PATCH/v1/webhooksMet à jour un webhook. Scope webhooks:manage. L'identifiant se passe dans le corps : { id, ... }.

La modification se fait par un PATCH sur la collection, avec l'id du webhook dans le corps aux côtés des champs à changer. Vous pouvez mettre à jour name, description, url, events et is_active. Passer is_active: false met le webhook en pause sans le supprimer : il cesse de recevoir des livraisons jusqu'à ce que vous le réactiviez. Comme à la création, tout type d'événement non reconnu est rejeté avec validation_error, et une url invalide renvoie également validation_error. Un identifiant introuvable renvoie not_found.

curl -X PATCH https://api.coffrify.com/v1/webhooks \
  -H "Authorization: Bearer cof_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "wh_2bX9...",
    "events": ["transfer.downloaded", "coffre.accessed"],
    "is_active": false
  }'

Supprimer un webhook

DELETE/v1/webhooksSupprime définitivement un webhook. Scope webhooks:manage. L'identifiant se passe dans le corps : { id }.

La suppression se fait par un DELETE sur la collection en passant { "id": "wh_..." } dans le corps. L'opération est définitive : le webhook cesse aussitôt de recevoir des livraisons et son secret est perdu. La réponse confirme la suppression.

$ curl -X DELETE https://api.coffrify.com/v1/webhooks \
    -H "Authorization: Bearer cof_live_..." \
    -H "Content-Type: application/json" \
    -d '{"id": "wh_2bX9..."}'
 
{ "id": "wh_2bX9...", "object": "webhook", "deleted": true }

Envoyer une livraison de test

POST/v1/webhooks/{id}/testEnvoie une livraison de test signée à l'URL du webhook et renvoie la réponse du destinataire. Scope webhooks:manage.

Pour valider votre intégration sans attendre un vrai événement, déclenchez une livraison de test. Le corps accepte event_type (un type du catalogue ou ping, valeur par défaut) et data (un objet libre inséré dans la charge utile). Coffrify émet vers votre URL une requête POST signée exactement comme une livraison réelle, mais marquée de l'en-tête X-Coffrify-Test-Delivery: true pour que votre récepteur puisse l'isoler de vos flux de production. La réponse vous restitue le code HTTP renvoyé par votre serveur, la durée de l'aller-retour, un extrait du corps de réponse et, le cas échéant, le message d'erreur réseau.

$ curl -X POST https://api.coffrify.com/v1/webhooks/wh_2bX9.../test \
    -H "Authorization: Bearer cof_live_..." \
    -H "Content-Type: application/json" \
    -d '{"event_type": "ping"}'
 
{
  "webhook_id": "wh_2bX9...",
  "event_id": "e7c1...",
  "event_type": "ping",
  "status": 200,
  "duration_ms": 184,
  "body_preview": "ok",
  "error": null,
  "test_delivery": true
}

Catalogue public des événements

GET/v1/webhooks/eventsListe tous les types d'événements pris en charge, regroupés par famille. Endpoint public, sans authentification.

Cet endpoint public renvoie l'inventaire complet des types d'événements que vous pouvez écouter, avec pour chacun sa famille et une description. Il est idéal pour découvrir les valeurs valides avant de construire votre tableau events. Les types se répartissent en familles : transfer.* (created, downloaded, expired, deleted, scanned, scan_clean, scan_infected, password_failed, geo_blocked, et autres), coffre.* (created, accessed, item_uploaded), collection.*, request.* pour la réception (created, submitted, completed, expired), ainsi que member.*, api_key.*, workspace.*, billing.*, domain.*, session.*, et l'événement ping.

Famille	Exemples de types	Cas d'usage
transfer	transfer.downloaded, transfer.expired, transfer.scan_infected	Suivre le cycle de vie et la sécurité d'un transfert
request	request.created, request.submitted, request.completed	Suivre une demande de réception (intake) de bout en bout
coffre	coffre.created, coffre.accessed, coffre.item_uploaded	Tracer les accès et dépôts dans une data room
api_key	api_key.created, api_key.revoked	Auditer les clés d'API de l'espace
workspace	workspace.plan_changed, workspace.usage_limit_reached	Réagir aux limites de plan et aux changements d'abonnement

Vérifier la signature des livraisons

Chaque livraison est signée avec le secret whsec_ du webhook, selon l'algorithme HMAC-SHA256. Coffrify joint deux formats de signature à chaque requête ; vérifiez-en au moins un avant de traiter le corps, et rejetez toute requête dont l'horodatage s'écarte de plus de 5 minutes de l'heure courante. Le format Standard Webhooks utilise les en-têtes webhook-id, webhook-timestamp (secondes Unix) et webhook-signature au format v1,<signature>, calculée sur la chaîne id.timestamp.corps. Le format historique Coffrify utilise l'en-tête X-Coffrify-Signature au format t=<timestamp>,v1=<signature>, calculée sur timestamp.corps. L'en-tête webhook-id sert aussi d'identifiant de livraison pour dédupliquer les rejeux côté récepteur.