Webhooks

À quoi servent les webhooks

Un webhook est un appel sortant : quand un événement se produit dans votre organisation, VIGIL-MESH contacte une URL que vous avez déclarée et lui transmet la description de l'événement. Le sens de l'échange est inversé par rapport à une consultation classique — ce n'est plus vous qui demandez « quoi de neuf ? », c'est la plateforme qui vous prévient. Cela permet de brancher les événements opérationnels sur vos propres outils : supervision, alerting, tickets, automatisations.

L'intérêt est la réactivité. Un relais qui tombe ou un device révoqué sont des faits qui appellent souvent une action rapide ; les découvrir en direct plutôt qu'à la prochaine ouverture de la console change la nature de la réponse. Les webhooks font le lien entre l'état du réseau, tel que la console le connaît, et le système d'information qui doit réagir — un rôle de premier plan dès qu'on exploite un parc réel.

Événements

Les webhooks portent sur des événements opérationnels : des faits concernant l'état et le cycle de vie du réseau, qui méritent d'être connus au moment où ils surviennent. Parmi eux :

• Relais indisponible : un relais devient injoignable, ce qui peut affecter l'établissement de certaines liaisons.
• Enrôlement en attente : une demande d'enrôlement attend une décision et ne devrait pas rester en suspens.
• Device révoqué : un device a perdu son accès au réseau — un fait de sécurité à propager et à tracer.
• … et les autres événements opérationnels du même ordre, qui signalent un changement d'état appelant attention ou action.

Ces événements recoupent naturellement le journal d'audit : une révocation, par exemple, est à la fois consignée dans la chaîne d'audit de l'organisation (voir /docs/console-audit) et poussée en webhook si vous l'avez configuré. Le journal garde la mémoire vérifiable ; le webhook assure la notification en direct. Les deux sont complémentaires.

Signature HMAC-SHA256

Un endpoint qui reçoit des appels sortants doit pouvoir distinguer un vrai événement d'une requête forgée par un tiers. Chaque webhook émis par VIGIL-MESH est donc signé en HMAC-SHA256 : à l'aide d'un secret partagé entre la plateforme et vous, une signature est calculée sur le contenu de l'appel et jointe à la livraison. Votre endpoint recalcule la même signature de son côté et la compare : si elles coïncident, l'appel est authentique et son contenu n'a pas été altéré.

1. 1
   Un secret est partagéUn secret propre à votre configuration de webhook est connu de la plateforme et de vous seuls. Il ne circule pas dans les appels.
2. 2
   L'appel est signéAu moment d'émettre l'événement, la plateforme calcule une signature HMAC-SHA256 sur le corps de la requête et la transmet avec.
3. 3
   Vous vérifiezVotre endpoint recalcule la signature à partir du corps reçu et du secret, puis la compare à celle fournie. En cas de divergence, l'appel est rejeté.

Cette signature relève du même esprit que le reste du modèle de sécurité : l'authenticité se prouve cryptographiquement plutôt que de se présumer. Le cadre d'ensemble — identités, signatures, chiffrement de bout en bout — est décrit dans /docs/securite.

Repli e-mail

Un endpoint de webhook peut être momentanément injoignable : maintenance, incident réseau, déploiement en cours. Pour qu'une notification importante ne se perde pas silencieusement dans ces trous, VIGIL-MESH prévoit un repli par e-mail. L'information vous parvient alors par un second canal, indépendant de la disponibilité de votre endpoint HTTP.

Le repli e-mail est un filet de sécurité, pas le canal principal. Le webhook reste la voie privilégiée pour l'intégration en temps réel avec vos outils ; l'e-mail garantit qu'un événement opérationnel — relais indisponible, enrôlement en attente, device révoqué — atteint une personne même quand la voie machine est temporairement coupée.