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.
- Accès requis
- Droit « Lancer un scan antivirus »
- Durée
- 15 min
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 :
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ête | Contenu |
|---|---|
Content-Type | application/json |
X-Webhook-Signature | HMAC-SHA256 du corps brut, calculé avec votre secret, en hexadécimal minuscule |
X-Webhook-Timestamp | Date d'envoi au format ISO 8601 |
Corps pour un fichier sain :
{
"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 :
{
"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.
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 :
- Calculez la signature sur les octets reçus, sans les reformater : un
JSON.stringifyd'un objet déjà analysé peut changer l'ordre ou les espaces et casser la comparaison. - Comparez avec
timingSafeEqual, jamais avec===. - Traitez chaque
scanIdune seule fois : une même notification peut arriver plusieurs fois. - Répondez par un code
2xxen 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
- Envoyez le fichier de test EICAR avec votre
callbackUrlet votrecallbackSecret(voir le démarrage rapide). - Votre récepteur reçoit un appel avec
"status": "INFECTED"et la signature est acceptée. - Modifiez une lettre du secret côté récepteur et recommencez : la signature est refusée avec
401.
Voir aussi
- Suivre une analyse par interrogation, pour les scans terminés en
ERROR - Référence : webhook