# 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.

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ê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 :

```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](/v1.0/antivirus/suivre-une-analyse).

## Vérifier le résultat

1. Envoyez le fichier de test EICAR avec votre `callbackUrl` et votre `callbackSecret` (voir le [démarrage rapide](/v1.0/antivirus/demarrage-rapide#4-vérifier-que-ça-marche)).
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

- [Suivre une analyse par interrogation](/v1.0/antivirus/suivre-une-analyse), pour les scans terminés en `ERROR`
- [Référence : webhook](/v1.0/antivirus/reference#webhook)
