Les webhooks Level envoient des événements d'alerte, d'appareil et de groupe à un point de terminaison HTTP que vous contrôlez. Utilisez-les lorsque votre intégration nécessite des mises à jour pilotées par les événements plutôt qu'une interrogation de 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 la gestion des événements idempotente.

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

Format de la requête

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`	Date et 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 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 un HMAC-SHA256 sur le corps exact de la requête JSON.

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

Lisez le corps brut de la requête sous forme d'octets.
Calculez le HMAC-SHA256 sur ces octets exacts, en utilisant le secret du webhook comme clé.
Encodez le condensé en hexadécimal minuscule.
Préfixez le condensé avec sha256=.
Comparez-le avec X-Level-Signature à l'aide d'une comparaison en temps constant.
Rejetez 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 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 de 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.
Placez les traitements plus longs dans votre propre file d'attente.
Retourner une réponse de succès 2xx en réponse après avoir accepté l'événement.

Les requêtes échouées peuvent être réessayées automatiquement, et un administrateur peut relancer manuellement une livraison depuis Level. L'un ou l'autre chemin peut 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 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, de sorte que le récepteur doit la traiter comme un doublon possible.

Voir Paramètres des webhooks pour le workflow complet de configuration et de journal de livraison.

Webhooks : Guide du développeur