Skip to content

Recevoir le résultat par webhook

Recevez le verdict de l'antivirus sur votre serveur et vérifiez la signature HMAC-SHA256 de chaque notification, avec un serveur complet.

GuideDeveloper
Required access
Droit « Lancer un scan antivirus »
Duration
15 min

This page has not been translated yet and is shown in French.

Avec un webhook, Wakastart appelle votre serveur dès que le verdict est connu. Chaque appel est signé avec le secret que vous avez fourni à l'envoi : vérifiez cette signature avant de croire le contenu.

Avant de commencer

  • Un endpoint HTTPS joignable depuis Internet, par exemple https://mon-app.exemple.fr/webhooks/antivirus.
  • Un secret aléatoire de 64 caractères au plus, rangé dans vos secrets. Générez-le par exemple avec openssl rand -hex 32.

Déclarer le webhook à l'envoi

Le webhook se déclare scan par scan, dans la requête d'envoi. Renseignez les deux champs :

Bash
curl -X POST "https://api.wakastart.app/api/antivirus/scans" \
  -H "x-api-key: sk_test_exemple" \
  -F "file=@contrat.pdf" \
  -F "callbackUrl=https://mon-app.exemple.fr/webhooks/antivirus" \
  -F "callbackSecret=$ANTIVIRUS_WEBHOOK_SECRET"

Sans callbackSecret, aucun webhook n'est envoyé.

Ce que vous recevez

Wakastart envoie un POST à votre URL, avec un corps JSON et deux en-têtes.

En-têteContenu
Content-Typeapplication/json
X-Webhook-SignatureHMAC-SHA256 du corps brut, calculé avec votre secret, en hexadécimal minuscule
X-Webhook-TimestampDate d'envoi au format ISO 8601

Corps pour un fichier sain :

JSON
{
  "scanId": "7b2e4f10-3c6a-4d8e-9f1b-2a5c8d0e6f42",
  "status": "CLEAN",
  "filename": "contrat.pdf",
  "fileHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "completedAt": "2026-10-23T09:42:03.118Z"
}

Pour un fichier infecté, le champ threatName s'ajoute après filename :

JSON
{
  "scanId": "c41d9e27-6b0a-4f3e-8a12-7d5b9c0e1f88",
  "status": "INFECTED",
  "filename": "facture.zip",
  "threatName": "Win.Test.EICAR_HDB-1",
  "fileHash": "275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f",
  "completedAt": "2026-10-23T09:42:04.502Z"
}

Seuls les verdicts CLEAN et INFECTED déclenchent un webhook.

Écrire le récepteur

Ce serveur Express vérifie la signature sur le corps brut reçu, avant toute analyse du JSON.

TypeScript
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const SECRET = process.env.ANTIVIRUS_WEBHOOK_SECRET!;
const app = express();

function isValidSignature(rawBody: Buffer, signature: string | undefined): boolean {
  if (!signature) return false;
  const expected = createHmac("sha256", SECRET).update(rawBody).digest("hex");
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(signature, "utf8");
  return a.length === b.length && timingSafeEqual(a, b);
}

const processed = new Set<string>(); // en production : une table en base

app.post(
  "/webhooks/antivirus",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    if (!isValidSignature(req.body, req.header("X-Webhook-Signature"))) {
      return res.status(401).send("signature invalide");
    }

    const event = JSON.parse(req.body.toString("utf8")) as {
      scanId: string;
      status: "CLEAN" | "INFECTED";
      filename: string;
      threatName?: string;
      fileHash: string;
      completedAt: string;
    };

    if (processed.has(event.scanId)) return res.sendStatus(200);
    processed.add(event.scanId);

    if (event.status === "CLEAN") {
      // Libérez votre copie du fichier associée à event.scanId
    } else {
      // Supprimez votre copie et prévenez l'utilisateur (event.threatName)
    }
    res.sendStatus(200);
  },
);

app.listen(3000, () => console.log("Récepteur antivirus sur :3000"));

Points importants :

  1. Calculez la signature sur les octets reçus, sans les reformater : un JSON.stringify d'un objet déjà analysé peut changer l'ordre ou les espaces et casser la comparaison.
  2. Comparez avec timingSafeEqual, jamais avec ===.
  3. Traitez chaque scanId une seule fois : une même notification peut arriver plusieurs fois.
  4. Répondez par un code 2xx en moins de 10 secondes ; faites les traitements longs après la réponse.

Comprendre les nouvelles tentatives

Wakastart considère la livraison réussie sur toute réponse 2xx. Sinon, ou si votre serveur ne répond pas dans les 10 secondes, il réessaie : trois tentatives au total, à 1 seconde puis 4 secondes d'intervalle. Après la troisième, la notification est abandonnée ; le verdict reste disponible par interrogation.

Vérifier le résultat

  1. Envoyez le fichier de test EICAR avec votre callbackUrl et votre callbackSecret (voir le démarrage rapide).
  2. Votre récepteur reçoit un appel avec "status": "INFECTED" et la signature est acceptée.
  3. Modifiez une lettre du secret côté récepteur et recommencez : la signature est refusée avec 401.

Voir aussi