Configurer un webhook

Les webhooks Coffrify permettent à votre infrastructure de recevoir des notifications HTTP en temps réel dès qu'un événement survient dans votre espace de travail (transfert téléchargé, membre invité, quota atteint, etc.). Chaque livraison est signée par HMAC-SHA256 avec un secret unique de format whsec_<hex> et suit la spécification Standard Webhooks, ce qui permet de vérifier l'authenticité de chaque requête côté receveur. L'API distingue les environnements : un webhook créé avec une clé cof_test_… ne reçoit que des événements de test ; une clé cof_live_… reçoit les événements de production. Les webhooks de sandbox (cof_sandbox_…) sont strictement isolés des deux autres environnements.

Endpoints disponibles

Authentification

Toutes les opérations de lecture (liste, livraisons, santé) requièrent le scope webhooks:read. Les opérations d'écriture (création, modification, suppression, test, simulation, rotation du secret, relance) requièrent le scope webhooks:manage. Passez votre clé API dans l'en-tête Authorization: Bearer <cof_live_…>. En environnement de développement, utilisez une clé cof_test_… pour isoler vos webhooks de test.

Créer un webhook

Corps de la requête (POST /v1/webhooks)

L'API impose une limite de 25 webhooks par espace de travail. Au-delà, la création retourne une erreur 409 validation_error. Le secret de signature (format whsec_<64 caractères hex>) est généré automatiquement et retourné une seule fois dans la réponse de création : stockez-le immédiatement dans vos variables d'environnement.

curl -X POST https://api.coffrify.com/v1/webhooks \
  -H "Authorization: Bearer cof_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mon receveur de production",
    "url": "https://mon-serveur.example.com/webhooks/coffrify",
    "events": ["transfer.downloaded", "transfer.expired", "member.invited"]
  }'

Réponse de création (201)

{
  "id": "wh_01j9abcdef1234567890abcd",
  "name": "Mon receveur de production",
  "description": null,
  "url": "https://mon-serveur.example.com/webhooks/coffrify",
  "events": ["transfer.downloaded", "transfer.expired", "member.invited"],
  "is_active": true,
  "signing_version": "v1",
  "retry_policy": null,
  "secret": "whsec_4a7f2c9e1b83d56f0a2e4c8b1d3f5e7a9c2b4d6e8f0a1b3c5d7e9f1a2b4c6d8e",
  "created_at": "2026-06-06T10:23:45.000Z"
}

Vérifier la signature côté receveur

Coffrify signe chaque livraison selon deux mécanismes complémentaires. Le premier suit la spécification Standard Webhooks : l'en-tête webhook-signature contient v1,<base64> calculé sur la chaîne <webhook-id>.<webhook-timestamp>.<corps JSON>. Le second est le format natif Coffrify : l'en-tête X-Coffrify-Signature contient t=<timestamp>,v1=<hex> calculé sur <timestamp>.<corps JSON>. Dans les deux cas, la clé HMAC est obtenue en décodant la partie hexadécimale après le préfixe whsec_.

# Exemple de vérification manuelle (Standard Webhooks)
WEBHOOK_ID="evt_01j9..."
TIMESTAMP="1749202800"
BODY='{"id":"evt_01j9...","object":"event","type":"transfer.downloaded",...}'
SECRET_HEX="4a7f2c9e..." # partie hex après whsec_
 
echo -n "${WEBHOOK_ID}.${TIMESTAMP}.${BODY}" \
  | openssl dgst -sha256 -mac HMAC -macopt "hexkey:${SECRET_HEX}" -binary \
  | base64

Tester et simuler un webhook

L'endpoint /test envoie un événement ping (ou le type choisi) signé vers votre URL et retourne le statut HTTP, la durée en millisecondes et un aperçu des 500 premiers caractères du corps de réponse. L'endpoint /simulate va plus loin : vous choisissez n'importe quel type du catalogue et injectez un payload arbitraire pour valider le comportement de votre receveur sur des cas précis (par exemple transfer.scan_infected avec un country_code spécifique). Dans les deux cas, l'en-tête X-Coffrify-Test-Delivery: true est ajouté pour que votre receveur puisse distinguer les appels de test des livraisons réelles.

# Test ping
curl -X POST https://api.coffrify.com/v1/webhooks/wh_01j9abcdef1234567890abcd/test \
  -H "Authorization: Bearer cof_live_…" \
  -H "Content-Type: application/json" \
  -d '{"event_type": "ping"}'
 
# Simulation d'un transfert infecté
curl -X POST https://api.coffrify.com/v1/webhooks/wh_01j9abcdef1234567890abcd/simulate \
  -H "Authorization: Bearer cof_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "transfer.scan_infected",
    "data": {"transfer_id": "tr_test_123", "file_count": 2}
  }'

Catalogue des types d'événements

Le catalogue contient 74 types d'événements stables répartis en familles : transfer (17), workspace (9), member (6), api_key (5), api_token (3), webhook (2), scim (2), saml (2), audit (2), gdpr (2), collection (4), coffre (5), request (4), domain (3), billing (3), session (2), rule (2), system (1 : ping). Certains types requièrent un plan spécifique (ex. transfer.scan_infected requiert pro, transfer.geo_blocked requiert ultra, workspace.sso_configured requiert entreprise). Consultez le catalogue complet via GET /v1/webhooks/event-catalog ou GET /v1/webhooks/events/by-family.

Mettre à jour un webhook

Corps de la requête (PATCH /v1/webhooks/{id})

# Ajouter transfer.e2e_created et configurer la politique de relance
curl -X PATCH https://api.coffrify.com/v1/webhooks/wh_01j9abcdef1234567890abcd \
  -H "Authorization: Bearer cof_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["transfer.downloaded", "transfer.expired", "transfer.e2e_created"],
    "retry_policy": {
      "max_attempts": 5,
      "disable_after_consecutive_failures": 50
    }
  }'

Rotation du secret de signature

Pour faire pivoter le secret sans interrompre les livraisons en cours, appelez POST /v1/webhooks/{id}/rotate-secret. Le paramètre optionnel grace_window_hours (1–168, défaut 24) définit la durée pendant laquelle l'ancien secret reste accepté par le moteur de livraison Coffrify. Pendant cette fenêtre de grâce, GET /v1/webhooks/{id}/secret-status expose les deux préfixes masqués (current_secret_prefix et previous_secret_prefix) et la date d'expiration grace_until pour vous aider à suivre la migration.

# Rotation avec 48 heures de grâce
curl -X POST https://api.coffrify.com/v1/webhooks/wh_01j9abcdef1234567890abcd/rotate-secret \
  -H "Authorization: Bearer cof_live_…" \
  -H "Content-Type: application/json" \
  -d '{"grace_window_hours": 48}'

Réponse de rotation

{
  "webhook_id": "wh_01j9abcdef1234567890abcd",
  "secret": "whsec_9b3e1f7a2c5d8e0b4f6a8c2e1d3f5b7a9e2c4d6f8a0b2d4e6f8a1c3e5d7f9b2",
  "rotated_at": "2026-06-06T10:30:00.000Z",
  "secret_grace_until": "2026-06-08T10:30:00.000Z",
  "grace_window_hours": 48
}

Consulter les livraisons et relancer

# Lister les 20 dernières livraisons
curl "https://api.coffrify.com/v1/webhooks/wh_01j9abcdef1234567890abcd/deliveries?limit=20&offset=0" \
  -H "Authorization: Bearer cof_live_…"
 
# Forcer la relance d'une livraison échouée
curl -X POST https://api.coffrify.com/v1/webhooks/deliveries/dlv_01j9xyz/retry \
  -H "Authorization: Bearer cof_live_…"
 
# Rejouer une livraison (succès ou échec)
curl -X POST https://api.coffrify.com/v1/webhooks/deliveries/dlv_01j9xyz/replay \
  -H "Authorization: Bearer cof_live_…"

Réponse de liste des livraisons

{
  "object": "list",
  "data": [
    {
      "id": "dlv_01j9xyz",
      "event_id": "evt_01j9abc",
      "event_type": "transfer.downloaded",
      "attempt_number": 1,
      "max_attempts": 5,
      "status": "success",
      "status_code": 200,
      "duration_ms": 142,
      "error_message": null,
      "attempted_at": "2026-06-06T10:25:00.000Z",
      "completed_at": "2026-06-06T10:25:00.142Z",
      "next_retry_at": null,
      "created_at": "2026-06-06T10:25:00.000Z"
    }
  ],
  "has_more": false,
  "total": 1
}

Codes d'erreur

Voir aussi

• Créer un premier transfert
• Authentification et clés API
• Catalogue complet des événements
• Référence API Webhooks
• Livraisons et rejouer une livraison