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
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 :
curl -X POST "https://api.nessflow.com/v1/webhooks/$WEBHOOK_ID/test" \
-H "Authorization: Bearer $NESSFLOW_TOKEN"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.
curl -X POST "https://api.nessflow.com/v1/webhooks/$WEBHOOK_ID/rotate-secret" \
-H "Authorization: Bearer $NESSFLOW_TOKEN"