Documentation

Webhooks

Some network events cannot wait for someone to open the console to be seen: a relay that becomes unavailable, an enrollment left pending, a device that has just been revoked. Webhooks push these operational events to your own system, in real time, instead of forcing you to poll the interface. Every call is signed with HMAC-SHA256 so you can verify its authenticity, and an e-mail fallback guarantees the information reaches you even if your endpoint is momentarily unreachable.

What webhooks are for

A webhook is an outbound call: when an event occurs in your organization, VIGIL-MESH contacts a URL you have declared and sends it the description of the event. The direction of the exchange is reversed compared with a classic lookup — you no longer ask “what's new?”; the platform notifies you. This lets you plug operational events into your own tools: monitoring, alerting, tickets, automations.

The point is reactivity. A relay going down or a revoked device are facts that often call for quick action; discovering them live rather than the next time the console is opened changes the nature of the response. Webhooks bridge the state of the network, as the console knows it, and the information system that must react — a first-rank role as soon as you operate a real fleet.

Pushed, not polled

The event comes to you as soon as it happens, without polling or manually checking the console.

Plugged into your tools

The URL you declare receives the events and relays them to your monitoring, your alerting or your automations.

Scoped to the organization

You only receive your tenant's events, in line with the isolation described in /en/docs/console-roles.

Events

Webhooks cover operational events: facts about the state and lifecycle of the network that deserve to be known the moment they occur. Among them:

Relay unavailable: a relay becomes unreachable, which may affect the establishment of some links.
Enrollment pending: an enrollment request is awaiting a decision and should not be left hanging.
Device revoked: a device has lost its access to the network — a security fact to propagate and trace.
… and the other operational events of the same kind, signaling a state change that calls for attention or action.

These events naturally overlap with the audit log: a revocation, for example, is both recorded in the organization's audit chain (see /en/docs/console-audit) and pushed as a webhook if you have configured one. The log keeps the verifiable memory; the webhook provides the live notification. The two are complementary.

HMAC-SHA256 signature

An endpoint that receives outbound calls must be able to tell a genuine event from a request forged by a third party. Every webhook emitted by VIGIL-MESH is therefore signed with HMAC-SHA256: using a secret shared between the platform and you, a signature is computed over the content of the call and attached to the delivery. Your endpoint recomputes the same signature on its side and compares them: if they match, the call is authentic and its content has not been altered.

1
A secret is sharedA secret specific to your webhook configuration is known only to the platform and to you. It does not travel in the calls.
2
The call is signedWhen emitting the event, the platform computes an HMAC-SHA256 signature over the request body and sends it along.
3
You verifyYour endpoint recomputes the signature from the received body and the secret, then compares it with the one provided. If they diverge, the call is rejected.

This signature follows the same spirit as the rest of the security model: authenticity is proven cryptographically rather than presumed. The overall framework — identities, signatures, end-to-end encryption — is described in /en/docs/securite.

E-mail fallback

A webhook endpoint can be momentarily unreachable: maintenance, a network incident, a deployment in progress. So that an important notification does not silently fall into those gaps, VIGIL-MESH provides an e-mail fallback. The information then reaches you through a second channel, independent of your HTTP endpoint's availability.

The e-mail fallback is a safety net, not the primary channel. The webhook remains the preferred path for real-time integration with your tools; e-mail guarantees that an operational event — relay unavailable, enrollment pending, device revoked — reaches a person even when the machine path is temporarily cut.

Does the e-mail fallback replace the webhook?

No. The webhook is the real-time integration channel; e-mail is a fallback that takes over when the endpoint is unreachable, so a notification does not vanish in silence.

How can I be sure a webhook really comes from VIGIL-MESH?

Through the HMAC-SHA256 signature: your endpoint recomputes the signature from the received body and the shared secret, and accepts the call only if it matches.

Do I receive events from other organizations?

No. Like the rest of the platform, webhooks are scoped to your tenant: you only receive your organization's events, with no cross access (see /en/docs/console-roles).