Antivirus
Soumettre un fichier au scan antivirus, suivre son statut et recevoir le résultat par webhook signé.
Le module antivirus analyse les fichiers que vos utilisateurs envoient, avant que votre application ne les accepte. L'analyse est asynchrone : vous soumettez le fichier, puis vous lisez son statut ou vous recevez le résultat sur votre propre URL.
Chaque scan consomme 1 crédit du client, débité à la soumission. L'appel doit porter un client et une application : utilisez le jeton d'un utilisateur de l'application ou une clé API liée à un client.
Cycle de vie d'un scan
Un fichier déclaré INFECTED est placé en quarantaine. Un fichier identique, déjà déclaré infecté pour le même client et la même application, est déclaré infecté immédiatement.
L'objet Scan
| Champ | Type | Description |
|---|---|---|
id | UUID | Identifiant du scan |
status | chaîne | PENDING, SCANNING, CLEAN, INFECTED ou ERROR |
filename | chaîne | Nom d'origine du fichier |
fileSize | entier | Taille en octets |
mimeType | chaîne | Type déclaré à l'envoi |
fileHash | chaîne (64) | Empreinte SHA-256, calculée pendant le scan |
priority | entier, 1 à 10 | Priorité de traitement, 1 étant la plus haute (défaut 5) |
callbackUrl | chaîne ou null | URL de rappel |
threatName | chaîne ou null | Nom de la menace détectée |
threatSeverity | chaîne ou null | HIGH pour un fichier infecté |
scanEngine, signatureVersion | chaîne ou null | Moteur et version des signatures |
scanDurationMs | entier ou null | Durée de l'analyse |
errorMessage | chaîne ou null | Cause d'un statut ERROR |
queuedAt, startedAt, completedAt | chaîne ISO 8601 ou null | Dates de mise en file, de début et de fin |
Soumettre un fichier
/api/antivirus/scansDroit requis : antivirus.scan. Corps multipart/form-data.
| Champ | Type | Obligatoire | Contraintes | Description |
|---|---|---|---|---|
file | fichier | oui | 100 Mo au plus | Fichier à analyser |
callbackUrl | chaîne | non | HTTPS, adresse publique, 500 caractères au plus | URL qui recevra le résultat |
callbackSecret | chaîne | non | 64 caractères au plus | Secret de signature du webhook. Obligatoire pour recevoir le webhook |
priority | entier | non | 1 à 10 | Défaut 5 |
Si une politique de scan est définie pour votre client ou votre application, le fichier doit en respecter la taille maximale, les types MIME autorisés et les extensions bloquées. Le type est déterminé d'après le contenu du fichier, pas d'après son nom.
curl -s -X POST https://api.wakastart.app/api/antivirus/scans \
-H "x-api-key: sk_test_exemple" \
-F "file=@ordonnance.pdf" \
-F "callbackUrl=https://api.mon-app.exemple.fr/webhooks/antivirus" \
-F "callbackSecret=$ANTIVIRUS_WEBHOOK_SECRET"const form = new FormData();
form.append("file", new Blob([buffer], { type: "application/pdf" }), "ordonnance.pdf");
form.append("callbackUrl", "https://api.mon-app.exemple.fr/webhooks/antivirus");
form.append("callbackSecret", process.env.ANTIVIRUS_WEBHOOK_SECRET!);
const res = await fetch("https://api.wakastart.app/api/antivirus/scans", {
method: "POST",
headers: { "x-api-key": process.env.WAKASTART_API_KEY! },
body: form,
});
const scan = await res.json(); // scan.status === "PENDING"Réponse 201
{
"id": "8d7c6b5a-8888-4e9f-8a0b-1c2d3e4f5a77",
"status": "PENDING",
"filename": "ordonnance.pdf",
"fileSize": 182344,
"mimeType": "application/pdf",
"priority": 5,
"callbackUrl": "https://api.mon-app.exemple.fr/webhooks/antivirus",
"queuedAt": "2026-10-23T09:20:00.000Z"
}Erreurs
| Statut | Message | Cause |
|---|---|---|
400 | Fichier requis | Aucun fichier dans le champ file |
400 | Antivirus service error | Fichier refusé par la politique (taille, type, extension), secret trop long ou appel sans client ni application |
402 | Antivirus service error | Crédits insuffisants pour le client |
413 | File too large | Fichier de plus de 100 Mo |
503 | Antivirus service error ou Antivirus service unavailable | Service momentanément indisponible ; le scan n'est pas créé |
Suivre le statut d'un scan
/api/antivirus/scans/{id}/statusDroit requis : antivirus.read. Réponse légère, adaptée à une interrogation régulière.
curl -s https://api.wakastart.app/api/antivirus/scans/8d7c6b5a-8888-4e9f-8a0b-1c2d3e4f5a77/status \
-H "x-api-key: sk_test_exemple"Réponse 200
{ "id": "8d7c6b5a-8888-4e9f-8a0b-1c2d3e4f5a77", "status": "CLEAN", "filename": "ordonnance.pdf", "completedAt": "2026-10-23T09:20:04.000Z" }Interrogez toutes les quelques secondes, avec un délai croissant, jusqu'à un statut final : CLEAN, INFECTED ou ERROR.
Lire le détail d'un scan
/api/antivirus/scans/{id}Droit requis : antivirus.read. Réponse : l'objet Scan complet, avec la menace détectée et l'empreinte du fichier. Le secret de rappel n'est jamais renvoyé.
Erreurs (pour les deux lectures) : 400 Validation failed (uuid is expected) ; 404 Antivirus service error si le scan n'existe pas ou appartient à un autre client.
Recevoir le résultat par webhook
Si vous avez fourni callbackUrl et callbackSecret, Wakastart envoie le résultat à votre URL dès la fin du scan, pour les statuts CLEAN et INFECTED. Aucun webhook n'est envoyé pour ERROR : interrogez alors le statut.
Requête reçue :
POST /webhooks/antivirus HTTP/1.1
Content-Type: application/json
X-Webhook-Signature: 5f2b1c…e9a0
X-Webhook-Timestamp: 2026-10-23T09:20:04.512Z
{
"scanId": "8d7c6b5a-8888-4e9f-8a0b-1c2d3e4f5a77",
"status": "CLEAN",
"filename": "ordonnance.pdf",
"fileHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"completedAt": "2026-10-23T09:20:04.000Z"
}| Élément | Description |
|---|---|
X-Webhook-Signature | HMAC-SHA256 du corps brut, avec votre callbackSecret, en hexadécimal |
X-Webhook-Timestamp | Date d'envoi ; elle ne fait pas partie de la signature |
threatName | Présent dans le corps quand status vaut INFECTED |
Vérifiez la signature sur le corps brut, avant tout traitement :
import { createHmac, timingSafeEqual } from "node:crypto";
export function isValidAntivirusWebhook(rawBody: Buffer, signature: string, secret: string) {
const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(signature ?? "");
return a.length === b.length && timingSafeEqual(a, b);
}Répondez 2xx en moins de 10 secondes. En cas d'échec, Wakastart réessaie deux fois (après 1 puis 4 secondes). Traitez le webhook de façon idempotente en vous fondant sur scanId.