Introduction

Les webhooks envoient des événements Level sortants vers vos propres systèmes. Lorsqu'un événement d'alerte, d'appareil ou de groupe sélectionné se produit, Level met en file d'attente une requête HTTP POST vers l'URL que vous configurez.

Cet article traite des webhooks d'événements sortants configurés sous Paramètres → Webhooks. Pour démarrer une automatisation Level à partir d'une requête entrante, voir Déclencheur de Webhook.

Pour les formats de requête, la vérification des signatures et les conseils sur les récepteurs, voir Webhooks : Guide du développeur.

⚙️ PRÉREQUIS

Un point de terminaison accessible publiquement qui accepte les requêtes HTTP POST avec un corps JSON.
Accès administrateur à votre organisation Level.
Un secret sécurisé pour la vérification des signatures.

Utilisez un point de terminaison HTTPS afin que le contenu des webhooks et les signatures soient chiffrés en transit.

Paramètres du webhook

Accédez à Paramètres → Webhooks. La page comporte deux onglets :

Webhooks répertorie vos destinations configurées.
Requêtes affiche les tentatives de livraison et les réponses.

Créer un webhook

Cliquez sur + Ajouter un webhook ou + Créer un webhook dans l'état vide.
Saisissez l' URL.
Saisissez un Secret de destination pour signer les requêtes.
Laissez Activé activé pour commencer la livraison, ou désactivez-le pour enregistrer le webhook en état suspendu.
Sous Événements à envoyer, choisissez tous les types d'événements actuellement disponibles ou sélectionnez des types individuels.
Cliquez sur Ajouter un webhook.

💡 CONSEIL : Générez un secret à haute entropie avec un gestionnaire de mots de passe et stockez-le dans le gestionnaire de secrets utilisé par votre service récepteur.

⚠️ AVERTISSEMENT : Le secret enregistré ne peut pas être consulté ultérieurement. Stockez-le avant de cliquer sur Ajouter un webhook. S'il est perdu ou exposé, modifiez le webhook, définissez un nouveau secret et mettez à jour votre service récepteur.

Types d'événements disponibles

Événement	`event_type`	Quand il est envoyé
Alerte active	`alert_active`	Une nouvelle alerte est déclenchée.
Alerte résolue	`alert_resolved`	Une alerte existante est résolue.
Appareil créé	`device_created`	Un appareil est ajouté.
Appareil mis à jour	`device_updated`	Les données ou la configuration de l'appareil changent.
Appareil supprimé	`device_deleted`	Un appareil est supprimé.
Groupe créé	`group_created`	Un groupe d'appareils est créé.
Groupe mis à jour	`group_updated`	Le nom ou la configuration d'un groupe change.
Groupe supprimé	`group_deleted`	Un groupe est supprimé.

Sélectionner tous les événements enregistre tous les types d'événements actuellement affichés dans Level. Vérifiez le webhook après la publication de nouveaux types d'événements si vous souhaitez vous y abonner.

Structure du payload

Chaque événement utilise cette enveloppe JSON :

{  "event_type": "device_created",  "event_id": "550e8400-e29b-41d4-a716-446655440000",  "occurred_at": "2026-03-13T18:30:00.000Z",  "data": {    "id": "..."  }}

Champ	Type	Description
`event_type`	chaîne de caractères	L'un des types d'événements configurés.
`event_id`	UUID	Identifie l'événement et reste stable lorsque le même payload est livré à nouveau.
`occurred_at`	Date/heure ISO 8601 en UTC	Heure à laquelle l'événement a été généré.
`data`	objet	Données d'événement spécifiques à la ressource.

Utilisez event_id comme clé d'idempotence. Une requête peut être répétée en raison d'un comportement de nouvelle tentative automatique ou d'une relance manuelle.

Consultez Webhooks : Guide du développeur pour le format de requête, la vérification des signatures et la liste de contrôle du récepteur.

Vérifier les signatures des requêtes

Lorsqu'un secret est configuré, Level calcule HMAC-SHA256 sur le corps exact de la requête JSON et envoie le résultat dans cet en-tête :

X-Level-Signature: sha256=

Vérifiez la signature avant d'analyser ou de traiter le JSON :

Lisez le corps brut de la requête sous forme d'octets.
Calculez HMAC-SHA256 sur ces octets exacts, en utilisant le secret du webhook comme clé.
Encodez le condensé en hexadécimal minuscule et faites-le précéder de sha256=.
Comparez la valeur calculée avec X-Level-Signature à l'aide d'une comparaison en temps constant.
Rejetez la requête si les valeurs ne correspondent pas.

ℹ️ REMARQUE : L'en-tête de signature est omis lorsque le webhook n'a pas de secret. Configurez un secret pour chaque webhook en production.

Renvoyez une réponse de succès 2xx après avoir accepté l'événement. Si le traitement peut prendre du temps, placez l'événement vérifié dans votre propre file d'attente et renvoyez une réponse avant d'effectuer le travail de longue durée.

Consulter les journaux de livraison

Ouvrez l'onglet Requêtes pour inspecter les tentatives de livraison enregistrées.

Chaque ligne inclut :

Statut de livraison.
Statut de la réponse HTTP, lorsque la destination en a renvoyé un.
URL de destination.

Ouvrez une ligne pour voir les détails tels que l'heure de l'événement, l'URL complète, le message d'erreur et le corps de la réponse.

Nouvelles tentatives automatiques

Les livraisons échouées peuvent être relancées automatiquement. Votre point de terminaison peut recevoir le même event_id plus d'une fois, même si une requête précédente a été traitée avec succès mais que sa réponse n'a pas atteint Level.

Stockez les identifiants d'événements traités ou rendez chaque opération naturellement idempotente.

Relancer manuellement une requête

Après avoir corrigé la destination ou le récepteur, ouvrez une requête et cliquez sur Relancer la requête. Level renvoie immédiatement le payload d'origine stocké.

⚠️ AVERTISSEMENT : Relancer une requête envoie à nouveau le même événement. Dédupliquez en utilisant event_id avant de créer des enregistrements ou d'effectuer d'autres opérations non idempotentes.

Gérer les webhooks existants

L'onglet Webhooks affiche chaque URL de destination et l'état d'activation. De là, vous pouvez modifier l'URL, le secret, la sélection des événements ou l'état d'activation, ou supprimer le webhook.

Désactiver Activé désactivé suspend les livraisons futures sans supprimer la configuration. Réactivez-le lorsque la destination est prête.

FAQ

Qui peut gérer les webhooks ? Les administrateurs de l'organisation peuvent créer, modifier, consulter, relancer et supprimer des webhooks.
Quel format Level utilise-t-il pour l'envoi ? Level envoie une requête HTTP POST avec Content-Type: application/json et l'enveloppe documentée ci-dessus.
Comment vérifier une requête ? Configurez un secret et vérifiez le X-Level-Signature HMAC sur le corps brut avant d'analyser le JSON.
Pourquoi ai-je reçu le même événement deux fois ? Une réponse en échec, une nouvelle tentative automatique ou une relance manuelle peuvent répéter une livraison. Dédupliquez avec event_id.
Pourquoi une requête est-elle marquée comme échouée ? Ouvrez-le sous Requêtes et vérifiez le code de statut, l'erreur et le corps de la réponse. Confirmez que l'URL est accessible publiquement et renvoie une réponse de succès 2xx de réponse.
Puis-je envoyer des événements à plusieurs points de terminaison ? Oui. Créez un webhook pour chaque destination et choisissez ses types d'événements séparément.
Puis-je récupérer un secret perdu ? Non. Définissez un nouveau secret sur le webhook et mettez à jour le service récepteur.

Paramètres du Webhook