Introduction

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

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

⚙️ PRÉREQUIS

Un point de terminaison HTTPS accessible publiquement, prêt à recevoir des requêtes POST avec un corps JSON.
Accès administrateur à votre organisation Level.

Paramètres Webhook

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

Webhooks — vos webhooks configurés
Requêtes — le journal de livraison de toutes les requêtes sortantes

Créer un Webhook

1. Cliquez sur + Add webhook (en haut à droite) ou + Create webhook (état vide).

2. Saisissez l' URL. C'est là que Level enverra les données d'événement en POST. Utilisez HTTPS.

3. (Facultatif) Saisissez un Secretde destination. Level l'utilise pour signer chaque requête sortante afin que votre point de terminaison puisse vérifier que la charge utile provient bien 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 plus être consulté après l'enregistrement. Copiez-le quelque part avant de cliquer sur Add webhook — vous en aurez besoin dans le code de votre point de terminaison pour vérifier les signatures.

4.. Le bouton Activé 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 dans 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 retiré 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. Passez à Envoyer tous les types d'événements si vous souhaitez une livraison compatible avec les futures versions.

6. Cliquez sur Add webhook pour enregistrer.

Structure de la charge utile

Chaque livraison de 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`	string	L'un des 8 types d'événements listés ci-dessus
`event_id`	UUID	Unique par événement ; stable entre les tentatives — utilisez-le pour dédupliquer
`occurred_at`	Date et heure ISO 8601 (UTC)	Quand l'événement a été généré
`data`	object	Charge utile spécifique à la ressource pour cet événement

💡 CONSEIL : Utilisez event_id pour rendre votre point de terminaison idempotent. Level réessaie automatiquement les livraisons échouées, de sorte qu'un même événement peut arriver plus d'une fois.

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

Vérification des signatures de requête

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

Pour vérifier :

Prenez le corps brut de la requête JSON sous forme de 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 X-Level-Signature de l'en-tête.
S'ils correspondent, la requête provient de Level.

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

Consulter les journaux de livraison

L'onglet Requêtes affiche toutes les requêtes sortantes que Level a tentées pour l'ensemble des webhooks configurés.

Chaque ligne affiche :

Statut — badge succès ou échec
Code de statut — le code de réponse HTTP de votre point de terminaison (ou -- si la connexion a échoué avant qu'une réponse ne soit reçue)
URL — la destination de cette requête

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

Le panneau de détails affiche :

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 vers laquelle Level a envoyé la requête
Message d'erreur — l'erreur de connexion ou HTTP, le cas échéant
Corps de la réponse — ce que votre point de terminaison a renvoyé (ou la sortie d'erreur brute)

Nouvelles tentatives automatiques

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

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

Relancer manuellement une requête échouée

Si vous avez résolu le problème sous-jacent et ne souhaitez pas attendre la prochaine tentative, cliquez sur Re-run request en bas du panneau de détails. Level renvoie immédiatement la charge utile originale.

⚠️ AVERTISSEMENT : Re-run request envoie à nouveau la même charge utile. 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

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

ℹ️ REMARQUE : Désactiver un webhook arrête la livraison sans le supprimer ni supprimer son historique de requêtes. Utilisez cette option lorsque votre point de terminaison est en cours de maintenance.

FAQ

Quel format Level utilise-t-il pour les charges utiles des webhooks ? Level envoie une requête HTTP POST avec un corps JSON. Chaque événement utilise la même enveloppe : event_type, event_id, occurred_at, et data. Le data L'objet contient la charge utile spécifique à la ressource pour ce type d'événement. Consultez la Level Developer Documentation pour les schémas complets par événement.
Comment puis-je vérifier qu'une requête provient de Level ? Définissez un secret sur le webhook. Level inclut un X-Level-Signature en-tête formaté comme sha256=<hex_digest> sur chaque requête. Calculez le HMAC-SHA256 du corps brut de la requête à l'aide de votre secret, puis comparez-le à la valeur de l'en-tête. Consultez Verifying Request Signatures ci-dessus.
Qui peut créer et gérer des webhooks ? La configuration des webhooks — y compris le journal des requêtes — est réservée aux administrateurs. Seuls les techniciens disposant d'un accès administrateur à votre organisation Level peuvent créer, modifier, consulter ou supprimer des webhooks.
Toutes mes requêtes s'affichent comme Échouées. Que dois-je vérifier ? Ouvrez une requête échouée dans le panneau de détails et lisez le message d'erreur et le corps de la réponse. Causes fréquentes : l'URL n'est pas accessible publiquement, votre point de terminaison a renvoyé un code de statut non-2xx, ou l'URL a été mal saisie. Corrigez le problème sous-jacent, puis utilisez Re-run request pour relancer sans attendre la fenêtre de nouvelle 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 de manière indépendante.
Que se passe-t-il après 3 tentatives de livraison échouées ? Level cesse les nouvelles tentatives et enregistre l'échec final. Le webhook reste activé et continuera de tenter les événements futurs — seule cette livraison spécifique est abandonnée. Vous pouvez toujours la relancer manuellement depuis l'onglet Requêtes.
J'ai perdu mon secret de webhook. Puis-je le récupérer ? Non. Le secret ne peut pas être consulté une fois le webhook enregistré. Modifiez le webhook pour définir un nouveau secret, puis mettez à jour le code de votre point de terminaison pour utiliser la nouvelle valeur.