Webhooks : vue d'ensemble

Les webhooks vous permettent de réagir en temps réel à ce qui se passe dans votre espace Coffrify, sans interroger l'API en boucle. Plutôt que de demander régulièrement « ce transfert a-t-il été téléchargé ? », vous déclarez une URL HTTPS et Coffrify vous y envoie un message dès qu'un évènement survient : un fichier téléversé, un transfert téléchargé, un coffre consulté, une demande de réception complétée, et bien d'autres. Cette page présente le fonctionnement général, l'anatomie d'un évènement, la réponse attendue de votre serveur et un panorama des sujets traités en détail dans les autres pages.

Qu'est-ce qu'un webhook

Un webhook est un point de terminaison HTTPS que vous hébergez et que vous enregistrez auprès de Coffrify. Lorsqu'un évènement abonné se produit, Coffrify envoie une requête POST vers cette URL avec un corps JSON décrivant ce qui vient d'arriver. Votre serveur reçoit la requête, vérifie sa signature, traite l'information puis répond avec un statut 2xx. C'est un mécanisme de notification poussée : Coffrify vous appelle, l'inverse de l'API REST où c'est vous qui appelez Coffrify.

Anatomie d'un évènement

Chaque livraison transporte un corps JSON dont la structure est stable d'un type d'évènement à l'autre. Quatre champs sont toujours présents au premier niveau : type identifie l'évènement, timestamp indique le moment où il s'est produit, id est son identifiant unique, et data contient la charge utile propre à l'évènement.

{
  "id": "evt_3hK2pQ9rT...",
  "type": "transfer.downloaded",
  "timestamp": "2026-06-10T14:32:07Z",
  "data": {
    "transfer": {
      "id": "trf_8xZ...",
      "short_code": "A1B2C3",
      "status": "active"
    }
  }
}

Répondre rapidement avec un 2xx

Votre point de terminaison doit renvoyer un code de statut 2xx (typiquement 200) le plus vite possible, idéalement en moins de quelques secondes. Coffrify considère toute réponse 2xx comme une livraison réussie. Un code hors de cette plage, un dépassement de délai ou une erreur réseau sont interprétés comme un échec et déclenchent un réessai.

Pour tenir ce budget de temps, n'effectuez pas de traitement lourd dans la requête elle-même. Accusez réception immédiatement, mettez l'évènement dans une file d'attente, puis traitez-le en arrière-plan. Cela évite que des temps de réponse longs ne soient comptés comme des échecs et ne déclenchent des réessais inutiles.

import express from "express";
 
const app = express();
 
// Conservez le corps brut pour vérifier la signature
app.post("/webhooks/coffrify", express.raw({ type: "application/json" }), (req, res) => {
  // 1. Vérifiez la signature à partir du corps brut (voir page signatures)
  // 2. Mettez l'évènement en file d'attente pour traitement asynchrone
  // 3. Répondez tout de suite
  res.status(200).send("ok");
});
 
app.listen(3000);

Configurer un webhook

Un webhook se crée via l'API avec une clé disposant du scope webhooks:manage. Vous fournissez l'URL de destination et, optionnellement, la liste des évènements auxquels vous souscrivez. Sans précision, l'abonnement par défaut est ["transfer.downloaded"].

curl -X POST https://api.coffrify.com/v1/webhooks \
  -H "Authorization: Bearer cof_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wh-prod-001" \
  -d '{
    "url": "https://exemple.com/webhooks/coffrify",
    "events": ["transfer.created", "transfer.downloaded", "transfer.expired"]
  }'

Vous pouvez ensuite lister vos webhooks avec GET /v1/webhooks (scope webhooks:read), modifier ou supprimer un webhook en passant son id dans le corps de la requête PATCH ou DELETE, et envoyer une livraison de test pour valider votre intégration de bout en bout. Chaque espace de travail peut compter au maximum 25 webhooks.

Panorama

Cette vue d'ensemble pose les fondations. Trois aspects sont détaillés séparément et méritent votre attention avant de passer en production.

• Catalogue d'évènements : les familles disponibles couvrent les transferts (transfer.* : created, downloaded, expired, deleted, scanned, scan_clean, scan_infected, password_failed, geo_blocked), les coffres (coffre.* : created, accessed, item_uploaded), les collections (collection.*), la réception (request.* : created, submitted, completed, expired), ainsi que member.*, api_key.*, workspace.*, billing.*, domain.*, session.* et l'évènement ping. La liste complète et à jour des types est accessible publiquement via GET /v1/webhooks/events.
• Signatures : chaque livraison est signée par HMAC-SHA256 avec votre secret whsec_, dans deux formats que vous pouvez vérifier. Le format Standard Webhooks utilise les en-têtes webhook-id, webhook-timestamp et webhook-signature. Le format Coffrify historique utilise l'en-tête X-Coffrify-Signature. La tolérance d'horodatage est de 5 minutes. Vérifiez toujours la signature avant de traiter l'évènement.
• Réessais : une livraison qui n'aboutit pas à une réponse 2xx est automatiquement retentée. Concevez votre point de terminaison pour être idempotent et pour absorber d'éventuels doublons sans effet de bord.