L'API Coffrify expose deux endpoints pour consulter le catalogue des événements webhook : un endpoint public (GET /v1/webhooks/events) accessible sans authentification et mis en cache 5 minutes, et un endpoint filtrable par famille (GET /v1/webhooks/events/by-family) qui nécessite le scope webhooks:read. Les 74 événements sont tous marqués stable et couvrent 17 familles : transfers, workspace, membres, clés API, tokens, webhooks, SCIM, SAML, audit, RGPD, collections, coffres (Data Room), demandes de fichiers, domaines, billing, sessions et règles d'automatisation. Certains événements sont réservés aux plans Pro, Ultra ou Entreprise : le champ required_plan l'indique explicitement dans chaque entrée du catalogue.
/v1/webhooks/eventsRetourne le catalogue complet des événements (public, sans authentification, cache 300 s).GET/v1/webhooks/events/by-familyRetourne le catalogue filtré par famille et les compteurs par famille (scope webhooks:read requis).Authentification
L'endpoint GET /v1/webhooks/events est public : aucune clé API n'est nécessaire. Il est prévu pour les générateurs de documentation et les explorateurs curl. L'endpoint GET /v1/webhooks/events/by-family exige une clé API avec le scope webhooks:read. Transmettez votre clé dans l'en-tête Authorization: Bearer cof_live_… (ou cof_test_… en environnement de test, cof_sandbox_… en sandbox).
Paramètres de requête
L'endpoint accepte quelques filtres optionnels (par famille, par plan). Le tableau ci-dessous récapitule les paramètres disponibles et leurs valeurs.
| Paramètre | Type | Requis | Description |
|---|---|---|---|
family | string | Non | Filtre les événements par famille (transfer, workspace, member, api_key, api_token, webhook, scim, saml, audit, gdpr, collection, coffre, request, domain, billing, session, rule, system). Disponible uniquement sur /by-family. |
Consulter le catalogue
L'appel le plus simple récupère tout le catalogue sans authentification. Les exemples ci-dessous montrent comment l'interroger dans chaque langage.
Réponse de GET /v1/webhooks/events
La réponse liste tous les types d'événements (object: list), regroupés par families. C'est cette liste qui fait foi : un webhook ne peut s'abonner qu'à des type présents ici.
Réponse de GET /v1/webhooks/events/by-family
La variante par famille renvoie chaque événement avec sa family et son niveau de stabilité, plus des compteurs par famille. Pratique pour construire une interface de sélection groupée.
Tableau des événements par famille
Le tableau ci-dessous recense chaque événement, le plan minimum requis et son déclencheur. Référez-vous-y pour savoir à quoi vous abonner selon votre cas d'usage.
| Famille | Événement | Plan minimum | Déclenchement |
|---|---|---|---|
| transfer | transfer.created | free | Un nouveau transfert est créé. |
| transfer | transfer.downloaded | free | Le destinataire récupère les URL de téléchargement. |
| transfer | transfer.expired | free | Le transfert atteint expires_at. |
| transfer | transfer.deleted | free | Le propriétaire supprime le transfert ou la lecture unique le consomme. |
| transfer | transfer.cloned | free | Un transfert expiré est republié via clone. |
| transfer | transfer.renamed | free | Le titre du transfert est modifié. |
| transfer | transfer.settings_changed | free | Mot de passe, expiration ou max_downloads sont modifiés. |
| transfer | transfer.scanned | free | Le job antivirus se termine (neutre). |
| transfer | transfer.scan_clean | pro | Aucune menace détectée. |
| transfer | transfer.scan_infected | pro | Malware détecté, fichiers mis en quarantaine. |
| transfer | transfer.scan_quarantined | pro | Verdict suspect retourné. |
| transfer | transfer.limit_reached | free | Le dernier téléchargement autorisé est consommé. |
| transfer | transfer.password_failed | free | Mot de passe incorrect soumis sur un transfert protégé. |
| transfer | transfer.geo_blocked | ultra | Téléchargement bloqué par la politique géographique. |
| transfer | transfer.preview_opened | free | Le destinataire ouvre la prévisualisation d'un fichier. |
| transfer | transfer.email_sent | free | L'URL du transfert est envoyée par email via Coffrify. |
| transfer | transfer.e2e_created | free | Un transfert zero-knowledge (E2E) est créé. |
| workspace | workspace.created | free | Un nouveau workspace est provisionné. |
| workspace | workspace.plan_changed | free | Le plan d'abonnement change. |
| workspace | workspace.payment_succeeded | free | Facture Stripe réglée. |
| workspace | workspace.payment_failed | free | Échec de paiement Stripe. |
| workspace | workspace.usage_limit_warning | free | 80 % d'un quota de plan atteint. |
| workspace | workspace.usage_limit_reached | free | 100 % d'un quota de plan atteint. |
| workspace | workspace.storage_limit_reached | free | Quota de stockage entièrement consommé. |
| workspace | workspace.member_limit_reached | free | Nombre maximal de sièges membres atteint. |
| workspace | workspace.sso_configured | entreprise | Configuration SSO/SAML ajoutée ou mise à jour. |
| member | member.invited | free | Une invitation workspace est envoyée. |
| member | member.accepted | free | Un utilisateur invité accepte l'invitation. |
| member | member.removed | free | Un membre est retiré du workspace. |
| member | member.role_changed | free | Le rôle d'un membre est mis à jour (owner / admin / member). |
| member | invitation.expired | free | Un lien d'invitation expire avant acceptation. |
| member | invitation.revoked | free | Une invitation est révoquée manuellement. |
| api_key | api_key.created | free | Une nouvelle clé API est créée. |
| api_key | api_key.revoked | free | Une clé API est révoquée. |
| api_key | api_key.rotated | free | Une clé API est renouvelée (rotation). |
| api_key | api_key.expired | free | Une clé API atteint expires_at. |
| api_key | api_key.suspicious_usage | ultra | Détection d'anomalie sur les patterns d'usage d'une clé. |
| api_token | api_token.created | free | Un token de téléversement délégué est émis. |
| api_token | api_token.used | free | Un token de téléversement délégué est consommé. |
| api_token | api_token.expired | free | Un token de téléversement délégué expire sans utilisation. |
| webhook | webhook.delivery_failed_final | free | Une livraison a épuisé son budget de retentatives. |
| webhook | webhook.endpoint_disabled | free | Un endpoint est automatiquement désactivé après des échecs consécutifs. |
| scim | scim.user_provisioned | entreprise | L'IdP crée un utilisateur via SCIM. |
| scim | scim.user_deprovisioned | entreprise | L'IdP désactive un utilisateur via SCIM. |
| saml | saml.login_succeeded | entreprise | Un utilisateur se connecte via SAML SSO. |
| saml | saml.login_failed | entreprise | L'assertion SAML est rejetée. |
| audit | audit.exported | free | Le journal d'audit est exporté. |
| audit | audit.policy_violated | ultra | Une action est refusée par une règle de politique. |
| gdpr | gdpr.deletion_requested | pro | Un sujet demande la suppression (RGPD art. 17). |
| gdpr | gdpr.export_requested | pro | Un sujet demande l'export de ses données (RGPD art. 20). |
| collection | collection.created | free | Une nouvelle collection est créée. |
| collection | collection.updated | free | Le nom ou la description d'une collection est mis à jour. |
| collection | collection.deleted | free | Une collection est supprimée. |
| collection | collection.item_added | free | Un transfert est ajouté à une collection. |
| coffre | coffre.created | pro | Une Data Room est créée. |
| coffre | coffre.deleted | pro | Une Data Room est supprimée. |
| coffre | coffre.accessed | pro | Un invité externe ouvre la Data Room. |
| coffre | coffre.item_uploaded | pro | Un fichier est déposé dans une section de la Data Room. |
| coffre | coffre.invitation_sent | pro | Une invitation est envoyée à un invité externe. |
| request | request.created | free | Une demande de fichiers est créée et envoyée. |
| request | request.submitted | free | Le destinataire soumet les fichiers demandés. |
| request | request.expired | free | La date limite passe sans soumission. |
| request | request.completed | free | Tous les fichiers requis sont reçus. |
| domain | domain.added | pro | Un domaine personnalisé est enregistré. |
| domain | domain.verified | pro | La vérification DNS réussit, le domaine est actif. |
| domain | domain.verification_failed | pro | La vérification DNS échoue après la date limite. |
| billing | billing.trial_started | free | Un essai gratuit est activé sur le workspace. |
| billing | billing.trial_ending | free | L'essai se termine dans 3 jours sans moyen de paiement. |
| billing | billing.subscription_cancelled | free | L'abonnement est annulé, le workspace rétrograde en fin de période. |
| session | session.created | free | Une nouvelle session de connexion depuis un appareil ou une IP non reconnus. |
| session | session.revoked | free | Une session est révoquée manuellement par l'utilisateur ou un admin. |
| rule | rule.triggered | pro | Une règle d'automatisation se déclenche et exécute ses actions. |
| rule | rule.disabled | pro | Une règle est désactivée automatiquement après avoir atteint son seuil d'erreurs. |
| system | ping | free | Événement de test déclenché manuellement. |
Erreurs
Seul l'endpoint par famille étant authentifié, les erreurs se limitent à l'absence de clé ou de scope webhooks:read. Le tableau ci-dessous les détaille.
| Code HTTP | Code erreur | Quand | Résolution |
|---|---|---|---|
| 401 | missing_api_key | En-tête Authorization absent sur /by-family. | Ajoutez Authorization: Bearer cof_live_… à votre requête. |
| 401 | invalid_api_key | La clé API n'existe pas ou ne correspond pas à l'environnement. | Vérifiez le préfixe : cof_live_…, cof_test_… ou cof_sandbox_…. |
| 401 | expired_api_key | La clé a atteint sa date expires_at. | Créez une nouvelle clé dans le tableau de bord ou via POST /v1/api-keys. |
| 401 | revoked_api_key | La clé a été révoquée. | Générez une nouvelle clé avec le scope webhooks:read. |
| 403 | scope_missing | La clé ne possède pas le scope webhooks:read. | Émettez une clé incluant le scope webhooks:read. |
| 429 | rate_limited | Quota de requêtes par minute dépassé. | Respectez les en-têtes X-RateLimit-Remaining et X-RateLimit-Reset renvoyés. |
| 500 | internal_error | Erreur interne inattendue. | Réessayez après quelques secondes. Si persistant, contactez le support Coffrify. |
Bonnes pratiques
Voir aussi
- Créer et gérer vos webhooks
- Vérifier la signature HMAC d'un webhook
- Rejouer et déboguer les livraisons échouées
- Référence API - Webhooks
- Référence API - Événements par famille