Webhook après validation d'un certificat

Ce webhook vous transmet le contenu d'un dossier dès sa clôture : items collectés, médias, URL du certificat, et le contexte métier que vous aviez fourni à la création du dossier (références, bénéficiaire, métadonnées).

Il existe un second webhook

Le webhook de résultat d'analyse vous livre, lui, le verdict de confiance du dossier (score, détection de falsification, analyses documentaires). Il part plus tard, quand l'analyse est terminée. Les deux sont indépendants et peuvent être activés ensemble.

Quand il part

Le webhook est envoyé à la clôture du dossier, quel que soit le canal qui la déclenche :

Canal	Déclencheur
Application mobile	L'utilisateur valide le dossier, y compris sur un dossier ouvert depuis un Certilink.
API	`GET /cases/close/:caseId` ou `GET /cases/close/certilink/:magicLinkToken` (voir Gestion des dossiers).
SDK mobile	Chaque photo certifiée par le SDK crée et clôture son propre dossier.

Un dossier ne donne lieu qu'à un envoi par clôture.

Configuration

Depuis votre backend

Vous configurez vous-même l'URL et le jeton du webhook avec l'API, sans intervention de Certificall.

POST /company-options/api-settings

Authentification : Authorization: Bearer <token> (voir Authentification). Le compte API utilisé doit disposer du droit de modification de l'entreprise.

Corps de la requête

Nom	Type	Requis	Description
`endpoint`	String	oui	URL HTTPS de votre endpoint, capable de recevoir des requêtes `POST`.
`authToken`	String	oui	Jeton que Certificall présentera à chaque appel.
`authorizationHeader`	Enum	non	Où placer le jeton : `authorization` (défaut, en-tête `Authorization: Bearer`) ou `security-token` (en-tête dédié).

Exemple

curl -X POST https://admin.certificall.app/certificall/api/company-options/api-settings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://votre-domaine.fr/webhooks/certificall/dossier",
    "authToken": "<jeton que Certificall vous présentera>",
    "authorizationHeader": "authorization"
  }'

Réponse 200

{
  "companyId": 42,
  "apiSettings": [
    {
      "apiName": "caseHook",
      "endpoints": { "sendCase": "https://votre-domaine.fr/webhooks/certificall/dossier" },
      "authorizationHeader": "authorization",
      "hasCredentials": true
    }
  ]
}

Le jeton n'est jamais réaffiché après enregistrement : la réponse et GET /company-options n'indiquent que la présence d'identifiants (hasCredentials). Pour le changer, renvoyez la requête avec le nouveau jeton.

Contraintes sur l'URL

Sont refusées : les URL qui ne sont pas en https, les adresses IP littérales (v4 ou v6), et les hôtes sans nom de domaine. Votre endpoint doit être exposé publiquement, sur un domaine résolvable.

Par Certificall

Les modes d'authentification HMAC-SHA256 (apiKey + apiSecretKey) et clé d'API dédiée (intégrations de type Make) ne se configurent pas depuis l'API. Transmettez à votre interlocuteur Certificall l'URL de votre endpoint et les identifiants à utiliser ; il les enregistrera sur votre entreprise.

Authentification de l'appel entrant

Selon le mode configuré, votre endpoint reçoit l'un des en-têtes suivants :

# Bearer (défaut)
Authorization: Bearer <authToken>
Content-Type: application/json

# En-tête dédié
security-token: <authToken>
Content-Type: application/json

# Clé d'API (intégrations de type Make)
x-make-apikey: <apiKey>
Content-Type: application/json

# HMAC-SHA256
Authorization: HMAC-SHA256 <apiKey>:<signature>
X-Api-Key: <apiKey>
Content-Type: application/json

Pour le mode HMAC, la signature est un HMAC-SHA256 du corps JSON tel qu'envoyé, calculé avec votre apiSecretKey. Vérifiez-la sur le corps brut de la requête, pas sur une re-sérialisation.

Pas d'authentification Basic

L'authentification Basic (identifiant et mot de passe) n'est pas proposée par ce webhook.

Payload

{
  "cfRef": "CAS-12345_CMP-42",
  "createdAt": "2026-05-13T08:24:15.000Z",
  "reportId": "CHANTIER-2026-001",
  "frame": "Constat sinistre auto",
  "closed": true,
  "caseUrl": "https://admin.certificall.app/certificall/share/case/<shareToken>",
  "items": [
    {
      "createdAt": "2026-05-13T08:22:01.000Z",
      "cfRef": "<référence de l'item>",
      "title": "Photo du véhicule",
      "description": "vehicule_001.jpg",
      "stepAction": "PHOTOGRAPHY",
      "geolocLatitude": "48.8566",
      "geolocLongitude": "2.3522",
      "imageUrl": "https://admin.certificall.app/certificall/images/<identifiant>"
    },
    {
      "createdAt": "2026-05-13T08:23:10.000Z",
      "cfRef": "<référence de l'item>",
      "title": "Immatriculation",
      "description": "AB-123-CD",
      "stepAction": "TEXT_FIELD",
      "geolocLatitude": "48.8566",
      "geolocLongitude": "2.3522",
      "imageUrl": ""
    }
  ],
  "context": {
    "beneficiaire": { "nom": "Dupont", "prenom": "Jean", "adresse": "123 rue de la Paix", "cp": "75001", "ville": "Paris" },
    "emetteur": "ACME Company",
    "reportRef": "DOSS-2025-001",
    "instructions": "Vérifier l'état général du matériel"
  },
  "metadata": { "dossierId": "DOSS-2025-001", "agence": "PAR-09" }
}

Enveloppe

Champ	Type	Description
`cfRef`	String	Référence publique du dossier, au format `CAS-<id>_CMP-<entreprise>`. Unique : c'est votre clé de déduplication.
`createdAt`	ISO 8601	Date de création du dossier.
`reportId`	String	Le `reportToken` que vous aviez fourni à la création du dossier, du Certilink ou de la photo SDK. C'est votre clé de rattachement.
`frame`	String	Nom de la trame du dossier.
`closed`	Boolean	Toujours `true` au moment de l'envoi.
`caseUrl`	URL	URL du certificat PDF. `null` si le dossier n'a pas de lien de partage.
`items`	Array	Les items collectés.
`context`	Object	Le contexte métier fourni à la création. Absent si aucun contexte n'a été fourni.

Items

Champ	Type	Description
`createdAt`	ISO 8601	Date de collecte de l'item.
`cfRef`	String	Référence unique de l'item.
`title`	String	Titre de l'étape dans la trame.
`description`	String	Valeur collectée : texte saisi, date, choix, ou titre du fichier pour une photo.
`stepAction`	Enum	Type de l'étape : `PHOTOGRAPHY`, `VIDEO`, `SIGNATURE`, `DOCUMENT_UPLOAD`, `TEXT_FIELD`, `NUMBER_FIELD`, `DATE_FIELD`, `TIME`, `EMAIL`, `SELECT`.
`geolocLatitude`, `geolocLongitude`	String	Coordonnées de la collecte.
`imageUrl`	URL	URL de l'image pour une `PHOTOGRAPHY` ou une `SIGNATURE`, chaîne vide sinon.
`extractedData`	Array	Présent uniquement si l'extraction de champs est configurée sur l'étape : liste de `{ key, label, value }`.

Contexte

Le contenu de context dépend de la façon dont le dossier a été créé :

Origine du dossier	Contenu de `context`
`POST /cases/create` ou `PATCH /cases/update` avec un `caseContext`	Les données de `visibleData` sous leurs clés internes : `beneficiaire` (`nom`, `prenom`, `adresse`, `cp`, `ville`), `emetteur`, `photoRef`, `reportRef`, `instructions`, `user`. Seules les clés renseignées sont présentes.
Certilink (`POST /certilink/create` avec un `context`)	L'objet `context` du Certilink, restitué tel quel.
Application sans contexte	`context` absent.

Métadonnées

metadata est un champ du dossier, à côté de context : vos clés-valeurs telles que fournies, que le dossier vienne de POST /cases/create, d'un Certilink ou du SDK mobile. La clé est absente quand le dossier n'en porte aucune.

Où mettre vos identifiants internes

Pour rattacher le dossier à votre système, utilisez reportToken (renvoyé dans reportId), disponible sur tous les canaux et seul champ sur lequel l'API filtre. Le champ metadata est un complément, restitué sur tous les canaux : identifiant de chantier, code agence, type de dossier, page d'origine…

Garanties de livraison

	Comportement
Réémission	Aucune. Si votre endpoint est injoignable ou répond en erreur, l'échec est journalisé côté Certificall et l'envoi n'est pas retenté.
Doublons	Un envoi par clôture. Gardez néanmoins un traitement idempotent sur `cfRef`.
Ordre	Non garanti entre dossiers.

Deux conséquences pratiques :

Répondez en 2xx rapidement et faites votre traitement métier en arrière-plan.
Prévoyez un filet. Un balayage périodique de GET /cases?format=metadata&closed=true&hours=… (voir Gestion des dossiers) rattrape les dossiers dont le webhook ne vous est pas parvenu.

Traitement côté partenaire

// POST /webhooks/certificall/dossier (votre route)
app.post('/webhooks/certificall/dossier', verifyToken, async (req, res) => {
  const { cfRef, reportId, caseUrl, items, metadata = {} } = req.body;

  // 1) Accuser réception tout de suite
  res.status(200).end();

  // 2) Retrouver votre dossier : reportId = votre reportToken
  const dossier = await db.findByReference(reportId);
  if (!dossier) return; // dossier inconnu : on ignore, sans erreur

  // 3) Idempotence sur cfRef
  if (await db.alreadyReceived(cfRef)) return;

  // 4) Exploiter le contenu
  const photos = items.filter(i => i.stepAction === 'PHOTOGRAPHY').map(i => i.imageUrl);

  await db.attachCertificate(dossier.id, { cfRef, caseUrl, photos, metadata });
});

Check-list

Endpoint exposé publiquement en HTTPS, sur un domaine résolvable.
URL et jeton enregistrés via POST /company-options/api-settings (ou transmis à Certificall pour HMAC et clé d'API).
Mode d'authentification vérifié à la réception.
reportToken renseigné à la création de vos dossiers, Certilinks ou photos SDK.
Traitement idempotent sur cfRef.
Réponse 2xx rapide, traitement métier découplé.
Filet de rattrapage sur GET /cases pour les dossiers sensibles.

Pour aller plus loin

Webhook de résultat d'analyse — le verdict de confiance du dossier
Intégration d'un bouton "Certifier" — le parcours complet Certilink → webhook
SDK mobile — photos certifiées depuis votre application

Quand il part​

Configuration​

Depuis votre backend​

Contraintes sur l'URL​

Par Certificall​

Authentification de l'appel entrant​

Payload​

Enveloppe​

Items​

Contexte​

Métadonnées​

Garanties de livraison​

Traitement côté partenaire​

Check-list​

Pour aller plus loin​