Webhook de résultat d'analyse

Ce webhook vous livre le verdict d'analyse d'un dossier : score de confiance global, signaux par dimension et, si des documents ont été analysés, le détail de chaque analyse documentaire.

Il est distinct du webhook après validation d'un certificat, qui vous transmet le contenu du dossier à sa clôture. Les deux peuvent coexister : ils répondent à deux besoins différents, à deux moments différents.

	Webhook du dossier	Webhook d'analyse
Déclencheur	clôture du dossier	fin de l'analyse du dossier
Délai	immédiat	de quelques secondes à ~15 minutes
Contenu	items déposés, médias, PDF certifié, vos métadonnées	`trustScore`, verdict, détail des analyses documentaires
Configuré par	vous (`/company-options/api-settings`) ou Certificall	Certificall uniquement
Répond à	« qu'est-ce qui a été collecté ? »	« puis-je faire confiance à ce qui a été collecté ? »

Quand il part exactement

L'analyse d'un dossier est asynchrone et n'est pas terminée à la clôture :

Vous déposez un document. L'analyse documentaire démarre aussitôt en arrière-plan, et sa complétion est attendue pour ce dossier.
Vous clôturez le dossier. Le PDF est scellé, la réponse est immédiate. Le dossier passe en « analyse en cours ».
Certificall attend le retour de toutes les analyses documentaires du dossier.
Dès la dernière revenue, le score global est recalculé et le webhook part.

Seules les analyses documentaires sont attendues. Les analyses d'image (photo d'une photo, doublon) et de contexte (géolocalisation, appareil, batterie) ne retardent pas l'envoi : elles alimentent le score si elles sont revenues à temps.

Un dossier sans document reçoit aussi ce webhook

Il n'y a alors aucune analyse à attendre : le webhook part juste après la clôture, avec les signaux de fraude disponibles et un documentAnalyses vide.

Délais à prévoir

Situation	Délai avant réception
Dossier sans document	quelques secondes après la clôture
Analyse documentaire nominale	de quelques secondes à une dizaine de minutes
Analyse qui n'est jamais revenue	15 minutes, puis envoi avec `progress: "failed"`
Signal de clôture perdu (incident)	rattrapé automatiquement, envoi jusqu'à ~25 minutes après la clôture

Dimensionnez vos écrans sur un statut « vérification en cours » mis à jour à la réception, jamais sur une attente bloquante.

Conditions d'émission

Le webhook n'est envoyé que si les trois conditions sont réunies :

L'option d'analyse est active pour votre entreprise. C'est un interrupteur global : désactivé, il coupe toutes les analyses et tous les avis.
Un webhook d'analyse est configuré sur votre entreprise (voir ci-dessous).
Une analyse exploitable a pu être produite. Si le calcul du verdict échoue durablement, le dossier cesse d'afficher « analyse en cours » mais aucun avis n'est émis : il n'y aurait rien d'exploitable à livrer.

Configuration

Configuration par Certificall

Contrairement au webhook du dossier, celui-ci ne se configure pas depuis l'API. Transmettez à votre interlocuteur Certificall l'URL de votre endpoint et le jeton à présenter ; il les enregistrera sur votre entreprise.

Contraintes sur l'URL

L'URL est validée avant chaque envoi. Sont refusées :

les URL dont le schéma n'est pas http ou https — utilisez https ;
les adresses IP littérales, et tout nom de domaine qui résout vers une adresse privée, de bouclage ou réservée (10.x, 172.16-31.x, 192.168.x, 127.x, 169.254.x, plages CGNAT et multicast, ULA et link-local IPv6) ;
les hôtes qui ne résolvent pas.

Votre endpoint doit donc être exposé publiquement, sur un nom de domaine résolvable.

Authentification

Trois modes, au choix, selon ce que votre endpoint sait vérifier :

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

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

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

Le jeton n'est jamais réaffiché après enregistrement : pour le changer, il est ressaisi.

Pas de signature HMAC sur ce webhook

Le webhook du dossier accepte une signature HMAC-SHA256 ; celui-ci non. Si l'authenticité de l'appelant est un enjeu pour vous, filtrez également par jeton partagé et, si besoin, par adresse IP source côté réseau.

Payload

{
  "caseId": 12345,
  "cfRef": "CAS-12345_CMP-1",
  "progress": "completed",
  "trustScore": 86,
  "analyzeStatus": "GOOD",
  "analysis": {
    "caseId": 12345,
    "trustScore": 86,
    "trustLevel": "GOOD",
    "itemsAnalyzed": 3,
    "signals": [
      { "key": "gps",      "score": 95, "trustLevel": "GOOD" },
      { "key": "device",   "score": 90, "trustLevel": "GOOD" },
      { "key": "document", "score": 88, "trustLevel": "GOOD" }
    ],
    "documentAnalyses": [
      {
        "itemId": 67890,
        "expectedDocumentTypes": ["INVOICE"],
        "detectedDocumentType": "INVOICE",
        "typeMatchScore": 100,
        "crossCheckResults": [
          { "fieldCode": "totalAmount", "fieldLabel": "Montant total", "match": "MATCH" }
        ],
        "crossCheckScore": 100,
        "suspicionScore": 96,
        "suspicionLevel": "NONE",
        "evaluation": 96,
        "progressStatusLevel": "ANALYSIS_COMPLETED",
        "trustScore": 97,
        "analysisDetails": [
          {
            "code": "FONT_CONSISTENCY",
            "label": "Cohérence des polices",
            "status": "VALID",
            "evaluation": 95,
            "suspicionLevel": "NONE",
            "weight": 2
          }
        ]
      }
    ]
  }
}

Enveloppe

Champ	Type	Description
`caseId`	Number	Identifiant du dossier. C'est votre clé de rattachement (voir ci-dessous).
`cfRef`	String	Référence lisible du dossier (`CAS-<id>_CMP-<company>`).
`progress`	String	`completed` : analyse complète. `failed` : finalisée en mode dégradé, une analyse n'est pas revenue à temps.
`trustScore`	Number	Score de confiance global du dossier (0-100, 100 = confiance maximale).
`analyzeStatus`	String	`GOOD` (70-100) \| `SUSPICIOUS` (30-69) \| `CRITICAL` (0-29).
`analysis`	Object	Analyse complète — strictement le même contenu que `GET /cases/:caseId/analysis`.

Le détail de analysis (signaux, analyses documentaires, critères de contrôle) est décrit dans API — Analyse documentaire.

Le webhook ne transporte ni vos métadonnées, ni votre reportToken

Contrairement au webhook du dossier, celui-ci ne renvoie que caseId et cfRef. Enregistrez la correspondance caseId → votre dossier au moment où vous créez le dossier (POST /cases/create renvoie l'id) : sans elle, vous ne saurez pas à quoi rattacher le verdict.

Exploiter `progress`

progress: "failed" signifie que le verdict a été arrêté sans que toutes les analyses soient revenues. Les scores présents restent lisibles, mais ils sont partiels : le signal document peut manquer ou être calculé sur une partie seulement des pièces.

Ne validez jamais automatiquement sur un failed — routez vers une revue manuelle, ou interrogez GET /cases/:caseId/analysis un peu plus tard : une analyse arrivée en retard met le dossier à jour.

Garanties de livraison

À lire avant de concevoir votre endpoint : ce webhook est un avis, pas un journal transactionnel.

	Comportement
Doublons	Possibles. Un incident au moment de la finalisation entraîne un rejeu, et une analyse arrivée tardivement peut corriger un verdict déjà livré : vous recevez alors un second envoi sur le même `caseId`, avec un score différent.
Perte	Possible. Si votre endpoint est injoignable, en erreur, ou met plus de 10 secondes à répondre, l'avis est perdu : il n'est pas réémis.
Ordre	Non garanti entre dossiers. Sur un même dossier, un envoi plus récent fait foi.

Trois conséquences pratiques :

Traitez chaque réception comme une mise à jour du dossier caseId, jamais comme une insertion. Un second avis sur le même dossier doit écraser le précédent, pas créer une ligne.
Répondez vite et en 2xx. Accusez réception immédiatement et faites votre traitement métier en arrière-plan ; au-delà de 10 secondes, Certificall abandonne l'envoi.
Prévoyez un filet. Pour les dossiers critiques, un balayage périodique des dossiers clôturés sans verdict reçu, via GET /cases/:caseId/analysis, rattrape les avis perdus.

Traitement côté partenaire

// POST /webhooks/certificall/analyse (votre route)
app.post('/webhooks/certificall/analyse', verifyToken, async (req, res) => {
  const { caseId, progress, trustScore, analyzeStatus, analysis } = req.body;

  // 1) Accuser réception tout de suite — le traitement métier vient après
  res.status(200).end();

  // 2) Retrouver votre dossier via le caseId enregistré à la création
  const dossier = await db.findByCaseId(caseId);
  if (!dossier) return; // dossier inconnu : on ignore, sans erreur

  // 3) Router selon le verdict
  const documentaire = analysis?.documentAnalyses?.[0];
  const decision =
    progress !== 'completed'  ? 'revue_manuelle' :
    analyzeStatus === 'GOOD'  ? 'valide' :
                                'revue_manuelle';

  // 4) Mise à jour (jamais une insertion : le webhook peut être rejoué)
  await db.update(dossier.id, {
    decision,
    trustScore,
    verdict: analyzeStatus,
    typeDetecte: documentaire?.detectedDocumentType ?? null,
    scoreFalsification: documentaire?.suspicionScore ?? null,
    analyseRecueLe: new Date(),
  });
});

Quand aucun webhook n'arrive

Cause	Comment le vérifier
Option d'analyse inactive sur votre entreprise	`GET /cases/:caseId/analysis` répond `403`
Aucun webhook d'analyse enregistré	à confirmer auprès de votre interlocuteur Certificall
Dossier jamais clôturé	`GET /cases?caseId=...` renvoie `closed: false`
Endpoint injoignable, en erreur, ou trop lent	vos propres logs d'accès ; l'avis n'est pas réémis
Verdict impossible à produire (incident durable)	`GET /cases/:caseId/analysis` reste sans score

Dans tous ces cas, GET /cases/:caseId/analysis reste la source de vérité : le webhook n'est qu'une notification de ce que cet endpoint sait déjà.

Check-list

Endpoint exposé publiquement en HTTPS, sur un domaine résolvable (pas d'IP littérale, pas d'adresse privée).
URL et jeton transmis à votre interlocuteur Certificall.
Mode d'authentification choisi et vérifié à la réception (Bearer, security-token ou x-make-apikey).
Correspondance caseId → votre dossier écrite à la création du dossier.
Traitement idempotent : une seconde réception met à jour, elle n'insère pas.
Réponse 2xx en moins de 10 secondes, traitement métier découplé.
Cas progress: "failed" traité explicitement, sans validation automatique.
Filet de rattrapage sur GET /cases/:caseId/analysis pour les dossiers sensibles.

Pour aller plus loin

API — Analyse documentaire — modèle de données complet et lecture du résultat à la demande
Faire analyser un document par API — le parcours complet, de la trame au verdict
Webhook après validation d'un certificat — le webhook de contenu du dossier
Analyse documentaire — administration — configuration des trames et des contrôles

Quand il part exactement​

Délais à prévoir​

Conditions d'émission​

Configuration​

Contraintes sur l'URL​

Authentification​

Payload​

Enveloppe​

Exploiter progress​

Garanties de livraison​

Traitement côté partenaire​

Quand aucun webhook n'arrive​

Check-list​

Pour aller plus loin​