Recevoir des notifications webhook à chaque dépôt dans l'Inbox

L'Inbox de Coffrify permet à vos interlocuteurs de déposer des fichiers sans compte. Chaque appel à POST /v1/inbox/submit crée une soumission (status: "received") et peut déclencher un webhook vers votre serveur. Cette page explique comment enregistrer un endpoint, souscrire aux événements request.submitted et request.completed, et valider la signature webhook-signature côté récepteur pour traiter ces notifications en toute confiance.

Endpoints concernés

Trois endpoints interviennent : créer un webhook (POST /v1/webhooks), consulter le catalogue d'événements et déclencher une soumission Inbox qui notifiera vos abonnés.

Authentification

La création et la gestion de webhooks nécessitent un scope `webhooks:manage` sur votre clé API (cof_live_… ou cof_test_…). La lecture seule (liste, historique de livraisons) utilise le scope webhooks:read. Le dépôt dans l'Inbox (/v1/inbox/submit) s'authentifie quant à lui avec un token Inbox au format cit_live_…, émis depuis le tableau de bord Coffrify et distinct de votre clé API.

Créer le webhook : corps de la requête

La création d'un webhook déclare l'URL de destination et les événements auxquels s'abonner. Le tableau ci-dessous détaille les champs acceptés.

Exemples d'appel

L'exemple ci-dessous crée un webhook abonné aux événements de dépôt Inbox. Choisissez votre langage.

curl -X POST https://api.coffrify.com/v1/webhooks \
  -H "Authorization: Bearer cof_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inbox notifications prod",
    "url": "https://votre-serveur.com/webhooks/coffrify",
    "events": ["request.submitted", "request.completed"]
  }'

Réponse à la création

La réponse renvoie l'objet webhook et, surtout, son secret de signature (whsec_…). Ce secret n'apparaît qu'à la création : conservez-le pour vérifier les livraisons.

{
  "id": "wh_01J9ABCDE2FGHIJK3LMNOP4QRS",
  "name": "Inbox notifications prod",
  "description": null,
  "url": "https://votre-serveur.com/webhooks/coffrify",
  "events": ["request.submitted", "request.completed"],
  "is_active": true,
  "signing_version": "v1",
  "retry_policy": null,
  "secret": "whsec_a3f8e2d1c09b7654a3f8e2d1c09b7654a3f8e2d1c09b7654a3f8e2d1c09b7654",
  "created_at": "2026-06-06T10:23:45.000Z"
}

Structure d'un événement livré

Coffrify signe chaque livraison selon le standard Standard Webhooks. Les en-têtes webhook-id, webhook-timestamp et webhook-signature sont toujours présents. L'en-tête X-Coffrify-Signature (format t=<ts>,v1=<hex>) est également envoyé pour compatibilité avec les intégrations antérieures.

{
  "id": "evt_01J9XYZ123456789ABCDEFGHIJ",
  "object": "event",
  "type": "request.submitted",
  "created": 1749204225,
  "data": {
    "submission_id": "sub_01J9XYZ987654321ZYXWVUTSRQ",
    "drop_box_id": "dbox_01J9ABC111222333444555666",
    "workspace_id": "ws_01J8AB12CD34EF56GH78IJ90KL",
    "requester_email": "alice@example.com",
    "requester_name": "Alice Martin",
    "files_count": 3,
    "total_size_bytes": 2097152,
    "status": "received",
    "source": "api",
    "tracking_token": "TRK_abcdefghijklmnopqrstuvwxyz",
    "tracking_expires_at": "2026-07-06T10:23:45.000Z"
  },
  "test": false
}

Erreurs

Les erreurs portent sur une URL invalide, un événement inconnu ou le scope webhooks:manage manquant. Le tableau ci-dessous indique la résolution.

Voir aussi

• Référence : POST /v1/webhooks
• Référence : GET /v1/webhooks/event-catalog
• Référence : POST /v1/inbox/submit
• Référence : POST /v1/webhooks/{id}/test
• Guide : Créer votre premier transfert et envoyer un webhook
• Guide : Gérer les demandes de fichiers (Requests)
• Guide : Configurer les préférences de notifications