Catalogue des événements

Chaque webhook que vous enregistrez reçoit des événements : des notifications JSON signées que Coffrify envoie à votre URL dès qu'une action se produit dans votre espace de travail (un transfert téléchargé, un fichier déposé dans un coffre, une demande de réception complétée, etc.). Ce document recense les familles d'événements réellement émises, le rôle de chaque type courant, la forme de la charge utile que vous recevez, et l'endpoint public qui retourne en permanence la liste complète et à jour.

Enveloppe d'un événement

Tous les événements partagent la même enveloppe. Le corps de la requête POST envoyée à votre endpoint est un objet JSON dont la structure ne change pas d'une famille à l'autre : seul le contenu de data varie selon le type. Le champ created est un horodatage Unix en secondes, et id est l'identifiant unique de la livraison (utilisable pour l'idempotence côté récepteur).

{
  "id": "3f2c8a10-7b4e-4d9a-9c21-5e8f0a1b2c3d",
  "object": "event",
  "type": "transfer.downloaded",
  "created": 1749571200,
  "data": {
    "transfer_id": "tr_8Kd2mP9xQ",
    "short_code": "a1b2c3"
  }
}

Familles d'événements

Chaque type suit la convention famille.action. Vous abonnez un webhook à une liste de types précis : si vous ne précisez aucun événement à la création, l'abonnement par défaut est ["transfer.downloaded"]. Voici les familles réellement émises et ce qu'elles couvrent.

Événements de transfert

C'est la famille la plus utilisée. transfer.downloaded se déclenche dès qu'un destinataire récupère les URL de téléchargement, et transfer.scanned est neutre : pour un routage typé, préférez transfer.scan_clean, transfer.scan_infected ou transfer.scan_quarantined.

{
  "object": "event",
  "type": "transfer.password_failed",
  "created": 1749571200,
  "data": {
    "transfer_id": "tr_8Kd2mP9xQ",
    "short_code": "a1b2c3"
  }
}

Coffres, collections et réception

Les familles coffre.*, collection.* et request.* couvrent respectivement les data rooms, les regroupements de transferts et les demandes de fichiers. Pour la réception, suivez request.submitted (le destinataire a déposé des fichiers) puis request.completed (tous les fichiers requis sont reçus).

Espace, facturation, membres et sécurité

Ces familles sont utiles pour la supervision interne : facturation, gestion des sièges, et surveillance des accès. workspace.usage_limit_warning se déclenche à 80 % d'un quota et workspace.usage_limit_reached à 100 %.

Lister tous les types disponibles

Plutôt que de coder en dur une liste qui peut évoluer, interrogez le catalogue en direct. L'endpoint GET /v1/webhooks/events est public (aucune authentification requise), ce qui le rend pratique pour les générateurs de documentation, les explorateurs et les scripts de validation. Il retourne tous les types, leur famille, leur description et, le cas échéant, le palier requis.

curl https://api.coffrify.com/v1/webhooks/events

{
  "object": "list",
  "total": 74,
  "families": ["transfer", "workspace", "member", "api_key", "coffre", "collection", "request", "domain", "billing", "session", "system"],
  "data": [
    {
      "type": "transfer.downloaded",
      "family": "transfer",
      "description": "Recipient successfully fetched download URLs.",
      "stability": "stable"
    },
    {
      "type": "transfer.scan_infected",
      "family": "transfer",
      "description": "Scan detected malware. Files quarantined.",
      "stability": "stable",
      "required_plan": "pro"
    }
  ]
}

Lorsque vous abonnez un webhook à une liste d'événements via POST /v1/webhooks, chaque type doit appartenir à ce catalogue : un type inconnu renvoie une erreur validation_error. Vérifiez donc vos noms d'événements contre GET /v1/webhooks/events avant de créer ou de mettre à jour un endpoint.