Les webhooks Level envoient des événements d'alerte, d'appareil et de groupe vers un point de terminaison HTTP que vous contrôlez. Utilisez-les lorsque votre intégration nécessite des mises à jour pilotées par des événements plutôt que d'interroger l'API publique.

Cet article couvre le format des requêtes et le comportement du récepteur. Pour créer un webhook, choisir des événements, gérer le secret et consulter les journaux de livraison dans Level, voir Paramètres des webhooks.

Pour les schémas de charge utile par événement, voir la Documentation développeur Level.

ℹ️ REMARQUE : Il s'agit de webhooks d'événements sortants. Pour démarrer une automatisation Level à partir d'une requête entrante, voir Déclencheur de webhook.

Avant de commencer

Vous avez besoin de :

Un accès administrateur pour configurer le webhook dans Level.
Un point de terminaison HTTPS accessible publiquement.
Un secret à haute entropie partagé entre Level et votre récepteur.
Un moyen de stocker les identifiants d'événements traités ou de rendre le traitement des événements idempotent.

Configurez la destination et la sélection d'événements sous Paramètres → Webhooks en suivant Paramètres des webhooks.

Format des requêtes

Level envoie une requête HTTP POST avec :

Content-Type: application/json

Lorsque le webhook possède un secret, Level envoie également :

X-Level-Signature: sha256=

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	Identifie le type d'événement.
`event_id`	UUID	Identifie l'événement et reste identique lorsque la charge utile est à nouveau livrée.
`occurred_at`	Datetime 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 la référence de charge utile de webhook pour le schéma de chaque data objet.

Types d'événements

`event_type`	Quand il est envoyé
`alert_active`	Une nouvelle alerte est déclenchée.
`alert_resolved`	Une alerte existante est résolue.
`device_created`	Un appareil est ajouté.
`device_updated`	Les données ou la configuration d'un appareil changent.
`device_deleted`	Un appareil est supprimé.
`group_created`	Un groupe d'appareils est créé.
`group_updated`	Le nom ou la configuration d'un groupe change.
`group_deleted`	Un groupe est supprimé.

Les types d'événements livrés à un point de terminaison dépendent de la sélection enregistrée dans Paramètres → Webhooks.

Vérifier la signature

Lorsqu'un secret est configuré, Level calcule le HMAC-SHA256 sur le corps exact de la requête JSON.

Vérifiez la requête avant d'analyser ou de traiter le corps :

Lire le corps brut de la requête en octets.
Calculer le HMAC-SHA256 sur ces octets exacts, en utilisant le secret du webhook comme clé.
Encoder le condensé en hexadécimal minuscule.
Préfixer le condensé avec sha256=.
Le comparer avec X-Level-Signature en utilisant une comparaison en temps constant.
Rejeter la requête si les valeurs ne correspondent pas.

⚠️ AVERTISSEMENT : L'analyse et la re-sérialisation du JSON avant le calcul du HMAC peuvent modifier les espaces blancs ou le formatage des champs et produire un condensé différent. Vérifiez le corps brut de la requête.

L'en-tête de signature est omis si le webhook n'a pas de secret. Configurez un secret pour les destinations en production.

Traiter les événements en toute sécurité

Un récepteur doit :

Accepter les requêtes uniquement via HTTPS.
Vérifier X-Level-Signature avant de faire confiance à la charge utile.
Valider event_type, event_id, occurred_at, et le data schéma.
Enregistrer event_id ou utiliser une opération idempotente.
Placer les travaux plus longs dans votre propre file d'attente.
Retourner une réponse de succès 2xx après avoir accepté l'événement.

Les requêtes échouées peuvent être relancées automatiquement, et un administrateur peut relancer manuellement une livraison depuis Level. Les deux chemins peuvent envoyer le même event_id plus d'une fois.

💡 CONSEIL : Utilisez event_id comme clé d'idempotence. Si votre récepteur l'a déjà traité, retournez un succès sans répéter l'opération.

Résoudre les problèmes de livraison

Utilisez Paramètres → Webhooks → Requêtes pour consulter les tentatives enregistrées. Les détails de la requête peuvent inclure :

Statut de livraison.
Statut de la réponse HTTP.
URL de destination.
Heure de l'événement.
Erreur de connexion ou HTTP.
Corps de la réponse.

Après avoir corrigé la destination, utilisez Relancer la requête pour renvoyer la charge utile stockée. Une nouvelle exécution utilise le même identifiant d'événement, donc le récepteur doit la traiter comme un possible doublon.

Voir Paramètres des webhooks pour le flux de travail complet de configuration et de journaux de livraison.

Webhooks : Guide du développeur