Introduction

Configurez les rappels HTTP pour envoyer les événements Level à vos propres systèmes en temps réel. Lorsqu'un événement se produit dans Level — une nouvelle alerte se déclenche, un appareil est ajouté, un groupe est mis à jour — Level envoie une demande POST à l'URL que vous spécifiez, afin que vous puissiez réagir dans vos propres outils sans interroger l'API.

Pour la référence API complète et les schémas de charge utile par événement, consultez la Documentation pour développeurs Level.

⚙️ CONDITIONS PRÉALABLES

Un point de terminaison HTTPS accessible au public prêt à recevoir des demandes POST avec un corps JSON.
Accès administrateur à votre organisation Level.

Paramètres Webhook

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

Webhooks — vos webhooks configurés
Demandes — le journal de livraison pour toutes les demandes sortantes

Création d'un Webhook

1. Cliquez sur + Ajouter un webhook (en haut à droite) ou + Créer un webhook (état vide).

2. Entrez l'URL de destination. C'est là que Level enverra les données d'événement. Utilisez HTTPS.

3. (Optionnel) Entrez un Secret. Level utilise ceci pour signer chaque demande sortante afin que votre point de terminaison puisse vérifier que la charge utile provient de Level.

💡 CONSEIL : Générez votre secret avec un gestionnaire de mots de passe ou openssl rand -hex 32. Utilisez une chaîne aléatoire à haute entropie.

⚠️ AVERTISSEMENT : Le secret ne peut pas être consulté à nouveau après l'enregistrement. Copiez-le avant de cliquer sur Ajouter un webhook — vous en aurez besoin dans votre code de point de terminaison pour vérifier les signatures.

4.. Le Activé le bouton bascule est activé par défaut. Laissez-le activé pour commencer à recevoir des événements immédiatement. Désactivez-le pour suspendre la livraison sans supprimer le webhook.

5. Sous Événements à envoyer, choisissez ce qui déclenche ce webhook :

Envoyer tous les types d'événements — Level envoie tous les types d'événements, y compris les nouveaux ajoutés à l'avenir.
Sélectionner les types à envoyer — choisissez parmi la liste ci-dessous.

Types d'événements disponibles

Événement	Quand il se déclenche
Alerte active	Une nouvelle alerte est levée sur un appareil
Alerte résolue	Une alerte existante est résolue
Appareil créé	Un nouvel appareil est ajouté à votre compte
Appareil supprimé	Un appareil est supprimé de votre compte
Appareil mis à jour	Les données ou la configuration d'un appareil existant changent
Groupe créé	Un nouveau groupe d'appareils est créé
Groupe supprimé	Un groupe d'appareils est définitivement supprimé
Groupe mis à jour	Le nom ou la configuration d'un groupe est modifié

ℹ️ REMARQUE : Si vous utilisez Sélectionner les types à envoyer, les nouveaux types d'événements ajoutés à Level à l'avenir ne seront pas inclus automatiquement. Basculez vers Envoyer tous les types d'événements si vous voulez une livraison compatible avec l'avenir.

6. Cliquez sur Ajouter un webhook pour enregistrer.

Structure de la charge utile

Chaque livraison webhook — quel que soit le type d'événement — utilise la même enveloppe JSON :

{
  "event_type": "device_created",
  "event_id": "a3f1b2c4-...",
  "occurred_at": "2026-03-13T18:30:00Z",
  "data": { ... }
}

Champ	Type	Description
`event_type`	chaîne	L'un des 8 types d'événements énumérés ci-dessus
`event_id`	UUID	Unique par événement ; stable lors des tentatives — utilisez ceci pour dédupliquer
`occurred_at`	Datetime ISO 8601 (UTC)	Quand l'événement a été généré
`data`	objet	Charge utile spécifique à la ressource pour cet événement

💡 CONSEIL : Utilisez event_id pour rendre votre point de terminaison idempotent. Level réessaye les livraisons échouées automatiquement, de sorte que le même événement peut arriver plusieurs fois.

ℹ️ REMARQUE : Pour les schémas complets par événement data, consultez la Documentation pour développeurs Level.

Vérification des signatures de demande

Si vous avez configuré un secret, Level inclut un en-tête X-Level-Signature sur chaque demande. Le format est sha256=<hex_digest>.

Pour vérifier :

Prenez le corps brut de la demande JSON en tant que chaîne.
Calculez HMAC-SHA256 de cette chaîne en utilisant votre secret comme clé.
Préfixez le résultat avec sha256= et comparez-le à la valeur de l'en-tête X-Level-Signature.
S'ils correspondent, la demande provient de Level.

ℹ️ REMARQUE : L'en-tête X-Level-Signature est présent uniquement quand un secret est configuré sur le webhook. Si vous n'en avez pas défini, envisagez de modifier le webhook pour l'ajouter.

Examen des journaux de livraison

L'onglet Demandes montre toutes les demandes sortantes que Level a tentées sur tous les webhooks configurés.

Chaque ligne affiche :

Statut — badge de succès ou d'échec
Code de statut — le code de réponse HTTP de votre point de terminaison (ou -- si la connexion a échoué avant une réponse)
URL — la destination de cette demande

Cliquez sur n'importe quelle ligne pour ouvrir le panneau de détail.

Le panneau de détail montre :

Heure de l'événement — quand l'événement s'est produit
Code de statut — réponse HTTP de votre serveur
URL complète — l'URL exacte que Level a envoyée à
Message d'erreur — l'erreur de connexion ou HTTP, le cas échéant
Corps de réponse — ce que votre point de terminaison a retourné (ou la sortie d'erreur brute)

Tentatives automatiques

Lorsqu'une livraison échoue, Level réessaye automatiquement — jusqu'à 3 tentatives au total. Chaque tentative attend environ 2 minutes, plus un délai aléatoire de 1 à 60 secondes. Après 3 tentatives échouées, Level arrête d'essayer et enregistre l'échec final. Aucune alerte n'est levée et le webhook n'est pas désactivé.

ℹ️ REMARQUE : Parce que Level réessaye automatiquement, le même événement peut être livré plus d'une fois. Utilisez event_id pour dédupliquer de votre côté.

Réexécution manuelle d'une demande échouée

Si vous avez corrigé le problème sous-jacent et ne voulez pas attendre la tentative suivante, cliquez sur Réexécuter la demande au bas du panneau de détail. Level renvoie la charge utile d'origine immédiatement.

⚠️ AVERTISSEMENT : Réexécuter la demande envoie la même charge utile à nouveau. Si votre point de terminaison n'est pas idempotent, cela peut créer des doublons. Vérifiez event_id avant le traitement.

Gestion des webhooks existants

Sur l'onglet Webhooks, chaque webhook configuré est répertorié avec son URL et son état activé. De là, vous pouvez modifier la configuration, l'activer ou le désactiver, ou le supprimer.

ℹ️ REMARQUE : Désactiver un webhook arrête la livraison sans le supprimer ni son historique de demandes. Utilisez ceci quand votre point de terminaison est en maintenance.

FAQ

Quel format Level utilise-t-il pour les charges utiles webhook ? Level envoie un HTTP POST avec un corps JSON. Chaque événement utilise la même enveloppe : event_type, event_id, occurred_at, et data. L'objet data contient la charge utile spécifique à la ressource pour ce type d'événement. Voir la Documentation pour développeurs Level pour les schémas complets par événement.
Comment vérifier qu'une demande provient de Level ? Définissez un secret sur le webhook. Level inclut un en-tête X-Level-Signature formaté comme sha256=<hex_digest> sur chaque demande. Calculez HMAC-SHA256 du corps brut de la demande en utilisant votre secret, puis comparez à la valeur de l'en-tête. Voir Vérification des signatures de demande ci-dessus.
Qui peut créer et gérer des webhooks ? La configuration des webhooks — y compris le journal des demandes — est limitée aux administrateurs. Seuls les techniciens ayant accès administrateur à votre organisation Level peuvent créer, modifier, afficher ou supprimer des webhooks.
Tous mes demandes affichent Échoué. Que dois-je vérifier ? Ouvrez une demande échouée dans le panneau de détail et lisez le message d'erreur et le corps de réponse. Causes courantes : l'URL n'est pas accessible au public, votre point de terminaison a retourné un code de statut non-2xx, ou l'URL a été mal tapée. Corrigez le problème sous-jacent, puis utilisez Réexécuter la demande pour réessayer sans attendre la fenêtre de tentative automatique.
Puis-je envoyer les mêmes événements à plusieurs points de terminaison ? Oui. Créez un webhook distinct pour chaque URL de destination. Chaque webhook s'abonne aux types d'événements indépendamment.
Que se passe-t-il après 3 tentatives de livraison échouées ? Level arrête de réessayer et enregistre l'échec final. Le webhook reste activé et continuera à tenter les événements futurs — seule cette livraison spécifique est abandonnée. Vous pouvez toujours la réexécuter manuellement à partir de l'onglet Demandes.
J'ai perdu mon secret webhook. Puis-je le récupérer ? Non. Le secret ne peut pas être consulté après l'enregistrement du webhook. Modifiez le webhook pour définir un nouveau secret, puis mettez à jour votre code de point de terminaison pour utiliser la nouvelle valeur.