# Recevoir les webhooks

> Abonner une adresse aux événements, vérifier chaque envoi, répondre vite et gérer les relances.

Un webhook évite de sonder : NessFlow appelle votre serveur quand un crawl se termine, qu’un export est prêt, que des recommandations sont générées ou qu’un signal de surveillance est détecté. Les webhooks sont réservés aux owners et admins de l’équipe.

## S’abonner

```bash expect=201
curl -X POST "https://api.nessflow.com/v1/webhooks" \
  -H "Authorization: Bearer $NESSFLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.exemple.fr/nessflow", "events": ["crawl.completed", "export.ready"]}'
```

L’adresse doit être en HTTPS et publique. La réponse porte le `secret` de signature (`whsec_…`), montré cette seule fois. Les offres en lecture seule gèrent leurs webhooks depuis l’écran **API** de l’équipe.

## Vérifier chaque envoi

Chaque envoi porte l’en-tête `NessFlow-Signature` : un horodatage `t` et une ou plusieurs signatures `v1`, chacune étant le HMAC-SHA256 de `t.corps brut` avec votre secret. Calculez la signature sur le corps BRUT, avant tout décodage JSON, comparez en temps constant, et refusez un horodatage de plus de 5 minutes (rejeu). La page des événements donne la fonction de vérification en PHP, Node et Python.

## Répondre vite

Répondez par un code `2xx` en moins de 10 secondes, puis traitez l’événement en tâche de fond. Tout autre résultat (erreur, délai dépassé, redirection) est relancé, 8 tentatives en tout sur 24 heures. Après 5 livraisons épuisées consécutives, l’abonnement est désactivé et les admins sont prévenus par e-mail.

## Dédupliquer

Un même événement peut arriver deux fois (une réponse perdue après un traitement réussi est indiscernable d’un échec). Dédupliquez sur l’en-tête `NessFlow-Event-Id`, identique d’une tentative à l’autre.

## Tester, puis réactiver

L’envoi de test part même vers un abonnement désactivé, ne compte jamais comme un échec, et son résultat se lit dans le journal :

```bash expect=202
curl -X POST "https://api.nessflow.com/v1/webhooks/$WEBHOOK_ID/test" \
  -H "Authorization: Bearer $NESSFLOW_TOKEN"
```

```bash
curl "https://api.nessflow.com/v1/webhooks/$WEBHOOK_ID/deliveries" \
  -H "Authorization: Bearer $NESSFLOW_TOKEN"
```

## Changer de secret sans rien perdre

Après une rotation, chaque envoi est signé avec l’ancien et le nouveau secret pendant 24 heures : déployez le nouveau sans coupure.

```bash
curl -X POST "https://api.nessflow.com/v1/webhooks/$WEBHOOK_ID/rotate-secret" \
  -H "Authorization: Bearer $NESSFLOW_TOKEN"
```