Webhooks de réception

La réception (intake) vous permet de collecter des fichiers auprès de tiers via une demande de dépôt. Plutôt que d'interroger l'API en boucle pour savoir si un destinataire a déposé ses documents, abonnez un webhook aux évènements de la famille request.*. Coffrify envoie alors une requête POST signée à votre URL dès qu'une demande est créée, qu'un dépôt est soumis, que la collecte est complète ou que la demande expire. Vous traitez l'information à l'instant où elle survient, en consommant un seul appel sortant par évènement.

Les évènements request.*

Quatre types d'évènements couvrent le cycle de vie d'une demande de réception. Ils sont tous stables et utilisables en production.

La liste complète et à jour des évènements est exposée publiquement, sans authentification, sur GET /v1/webhooks/events. Vous pouvez la consulter pour découvrir les nouvelles familles ou vérifier les libellés exacts.

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

Créer un webhook sur la famille request

Indiquez un name, l'url qui recevra les requêtes et la liste des events à écouter. Pour la réception, abonnez-vous aux quatre évènements request.*. La réponse renvoie le secret (préfixe whsec_) qui sert à vérifier les signatures : il n'est montré qu'à la création, conservez-le côté serveur.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
 
const webhook = await coffrify.webhooks.create({
  name: 'Réception - dépôts',
  url: 'https://exemple.com/webhooks/coffrify',
  events: [
    'request.created',
    'request.submitted',
    'request.completed',
    'request.expired',
  ],
});
 
// Affiché une seule fois, à stocker de façon sûre.
console.log(webhook.secret); // whsec_...

Forme d'un évènement reçu

Chaque livraison est un POST dont le corps JSON suit une enveloppe stable. Le champ type porte le nom de l'évènement, data contient les informations propres à la demande, et id identifie l'évènement de façon unique (utile pour la déduplication).

{
  "id": "a1b2c3d4-...",
  "type": "request.created",
  "created_at": "2026-06-10T09:24:00.000Z",
  "workspace_id": "ws_...",
  "data": {
    "request_id": "...",
    "title": "Pièces justificatives - dossier 4821",
    "short_code": "k3p9x2m7",
    "created_at": "2026-06-10T09:24:00.000Z"
  }
}

Le request_id du champ data est la référence à reprendre pour interroger la demande ou ses soumissions via l'API REST. Les évènements request.submitted, request.completed et request.expired partagent la même enveloppe, seul le contenu de data varie selon l'étape.

Recevoir et vérifier la livraison

Coffrify émet à la fois les en-têtes Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature) et des en-têtes hérités (X-Coffrify-Signature, X-Coffrify-Event-Id, X-Coffrify-Event-Type). Vérifiez la signature avant de traiter le corps : calculez un HMAC-SHA256 avec votre secret sur la chaîne webhook-id.webhook-timestamp.corps_brut, puis comparez au champ v1 de l'en-tête webhook-signature. Tout vérificateur compatible Standard Webhooks fonctionne sans adaptation.

import express from 'express';
 
const app = express();
 
// Conservez le corps BRUT : la signature porte sur les octets exacts.
app.post('/webhooks/coffrify',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const event = JSON.parse(req.body.toString('utf8'));
 
    switch (event.type) {
      case 'request.created':
        console.log('Demande envoyée', event.data.request_id);
        break;
      case 'request.submitted':
        console.log('Nouveau dépôt', event.data.request_id);
        break;
      case 'request.completed':
        console.log('Collecte complète', event.data.request_id);
        break;
      case 'request.expired':
        console.log('Demande expirée', event.data.request_id);
        break;
    }
 
    // Répondez 2xx rapidement pour accuser réception.
    res.sendStatus(200);
  });

Réessais et réponses attendues

Répondez avec un code 2xx dès que vous avez accusé réception, sans attendre la fin de votre traitement métier. Toute réponse non 2xx, un délai dépassé ou une erreur réseau déclenche une série de réessais avec un intervalle croissant, étalée sur environ 72 heures. Le même id d'évènement est conservé d'une tentative à l'autre, ce qui rend la déduplication fiable.

• Validez la signature, répondez 2xx, puis traitez en arrière-plan : un traitement lent peut faire expirer la connexion et provoquer un réessai inutile.
• Une URL injoignable de façon répétée finit par désactiver le webhook ; surveillez vos livraisons depuis votre espace.
• Un évènement de test (webhook.test) peut être envoyé depuis l'interface pour valider votre point de terminaison avant la mise en production.

Du dépôt à l'action

Un flux de réception typique enchaîne ces étapes sans aucune interrogation périodique. Le webhook porte l'évènement, votre code réagit, puis va chercher le détail via le request_id quand il en a besoin.

1. Vous créez une demande de dépôt (request.created part vers votre webhook).
2. Le tiers dépose ses fichiers ; request.submitted vous prévient en temps réel.
3. Lorsque tout le requis est reçu, request.completed déclenche la suite de votre processus (notification interne, classement, démarrage d'un traitement).
4. Si l'échéance passe sans soumission, request.expired vous laisse relancer le destinataire ou clôturer le dossier.