Intégration des webhooks

Ce document a pour but de donner aux clients un aperçu de la façon dont les données des capteurs Dryad peuvent être accessibles via les Webhooks.

Dryad permet aux clients de recevoir les données des capteurs via des webhooks en utilisant la nouvelle fonctionnalité intégration API Silvanet dans la Site Management App Silvanet.

---

Qu'est-ce qu'un Webhook

Les webhooks envoient des messages lors d'événements spécifiques dans des formats comme JSON, XML ou des données encodées en formulaire vers des endpoints HTTP(S) spécifiques configurés dans votre application. Silvanet utilise JSON comme type de contenu pour ses messages webhook.

 ---

Comment fonctionnent les Webhooks

Un webhook est un service qui écoute des événements spécifiques et envoie un message à une URL désignée (l'endpoint) de votre application lorsque ces événements se produisent. Par exemple, Dryad peut envoyer un webhook à chaque fois qu'un événement d'alerte incendie se produit, qui sera alors affiché dans votre application au sein de la Site Management App Silvanet.

Le webhook se compose des éléments suivants :

• Messages - Ce sont les webhooks envoyés. Un message peut contenir des contenus et quelques autres propriétés.

• Application - C'est là où les messages sont envoyés. Vous pouvez créer une application par organisation sur votre plateforme.

• Endpoints - Les endpoints sont les URLs vers lesquelles les messages seront envoyés. Chaque application peut avoir plusieurs endpoints, et chaque message envoyé à cette application sera transmis à tous, sauf si vous n'êtes pas abonné à certains événements pour chaque endpoint. Les endpoints écoutent les messages webhook.

• Événement - Lorsqu'un événement se produit, il déclenche l'envoi d'un message webhook.

Le schéma suivant montre comment les webhooks sont envoyés à votre endpoint lorsqu'un événement spécifique se produit.

---

Avantages de l'utilisation des Webhooks

• Les clients peuvent ajouter autant d'endpoints qu'ils le souhaitent à leur application (Portail Webhook) et les modifier.
• Les clients peuvent choisir quels types d'événements sont envoyés à quel endpoint. Par défaut, tous les messages sont envoyés à tous les endpoints.
• Les webhooks utilisent des requêtes HTTP sans état, ce qui garantit qu'aucune connexion persistante n'est requise.
• Les webhooks suivent un modèle orienté événement, où un message n'est déclenché que lorsque des événements spécifiques se produisent, ce qui réduit la communication inutile.
• Les webhooks permettent de rejouer les messages passés et échoués.

---

Configuration des Webhooks

La fonctionnalité intégration API Silvanet dans la Site Management App Silvanet vous permet de configurer des webhooks en créant une application pour chaque organisation que vous avez, puis en ajoutant des endpoints à chaque application. Avec ces endpoints, vous pouvez vous abonner aux types d'événements souhaités, voir les messages et récupérer/rejouer les messages passés ou échoués.

 ---

Créer une Application d'Intégration

• Connectez-vous à la Site Management App Silvanet avec vos identifiants.
• Dans la barre latérale, cliquez sur Intégration API.

• Le tableau de bord Intégration API Silvanet s'affiche.

• Cliquez sur le bouton Créer une application pour créer une nouvelle application d'intégration.

• Dans la boîte de dialogue Créer une nouvelle application d'intégration, sélectionnez l'organisation pour laquelle vous souhaitez créer l'application. Par exemple, Dryad Internal.

• Cliquez sur le bouton Valider pour créer l'application

  

   

  • L'application que vous avez créée apparaîtra sous Intégrations API actuelles.

   

  

   

 ---

Ajouter un Endpoint

Pour recevoir des messages, vous devez ajouter un endpoint à l'application. Bien sûr, vous pouvez ajouter plusieurs endpoints.

• Sur la page Intégration API Silvanet, sous Intégrations API actuelles, cliquez sur le nom de l'application que vous souhaitez configurer.
• La page de l'application s'affiche, et le nom de l'application apparaît en haut à gauche de la page.
• Cliquez sur l'onglet Endpoints si ce n'est pas déjà sélectionné par défaut.
• Cliquez sur le bouton Ajouter un endpoint.

Sur la page Nouveau endpoint, configurez les éléments suivants :

• URL du endpoint - Entrez ici l'URL de votre endpoint. Si vous n'avez pas de endpoint, vous pouvez cliquer sur l'option "Configurer un endpoint ou tester avec Svix Play." Cela générera automatiquement un endpoint et remplira la zone de texte pour vous. Vous pouvez aussi utiliser un service comme webhook.site pour générer une URL pour votre endpoint HTTP.
• Description - Entrez ici une description optionnelle indiquant à quoi sert ce endpoint.
• S'abonner aux événements - Sélectionnez un ou plusieurs types d'événements auxquels vous souhaitez vous abonner en cochant les cases. Si vous souhaitez ajouter tous les types d'événements d'un groupe spécifique, cliquez simplement sur le groupe.

• (Optionnel) Configuration avancée - cliquez pour développer cette section.
  • Cochez la case Limitation du débit du endpoint (throttling).
  • Limite de débit (par seconde) - indiquez le nombre maximal de messages webhook autorisés à être envoyés à ce endpoint par seconde. Par exemple, saisissez 10 si vous souhaitez limiter à 10 messages par seconde. 0 signifie illimité

• Cliquez sur le bouton Créer.

• Le endpoint est ajouté à votre application. Votre page devrait ressembler à ceci :

  

Voir les messages

Avec l'onglet Endpoints sélectionné, faites défiler la page vers le bas jusqu'à voir la vue en tableau. Elle affiche tous les messages reçus avec leur TYPE D'ÉVÉNEMENT, ID DU MESSAGE et TIMESTAMP.

• Dans le tableau, cliquez sur un message pour afficher son contenu. Vous serez redirigé vers l’onglet Journaux. Le contenu du message est simplement un objet JSON.

Tentatives de message

Il existe deux types de tentatives de message, identifiées comme suit :

• indique qu’un événement webhook a réussi et qu’un message webhook a été envoyé à votre application.

• indique qu’un événement webhook a échoué en raison de l’indisponibilité ou de la désactivation de l’endpoint, ou à cause d’une erreur serveur.

Rejouer les messages

Utilisez les options suivantes pour rejouer des messages afin de récupérer les messages passés ou échoués :

• Rejouer tous les messages - Vous pouvez rejouer tous les messages passés ou échoués en utilisant le bouton replay pour recevoir ces messages webhook dans votre application.

• Cette option est adaptée pour rejouer tous les messages à partir d’un certain moment dans le passé.

  • Dans le tableau, utilisez le TIMESTAMP pour trouver le message le plus proche de l’heure souhaitée. Par exemple, si vous souhaitez rejouer tous les messages à partir de 14h54, repérez le message avec l’horodatage le plus proche. Cliquez sur le menu à trois points de ce message puis sélectionnez Rejouer.

• La boîte de dialogue suivante s’affichera avec trois options :
  • Renvoyer ce message - sélectionnez cette option pour rejouer le message que vous avez choisi dans le tableau.
  • Renvoyer tous les messages échoués depuis - cela rejouera tous les messages échoués depuis l’heure de l’événement de ce message.
  • Rejouer tous les messages manquants depuis - cela rejouera tous les messages qui n’ont jamais été tentés pour cet endpoint depuis le type d’événement de ce message.

Filtrer les types d’événements / messages

Il existe plusieurs façons de filtrer les messages. 

• Filtrez les types d’événements ou les messages selon les tentatives de message à l’aide des boutons suivants :
  • Tous
  • Réussis
  • Échoués
• Utilisation des filtres : Cliquez sur le menu Filtres pour l’ouvrir.
  • Types d’événements : Filtrez les messages par type d’événement en cliquant sur Filtres > Type d’événement puis en recherchant ou sélectionnant le(s) type(s) d’événement.
  • Tags : Filtrez les messages par tags.
  • Après la date / Avant la date : Si vous connaissez approximativement la date d’envoi du message, vous pouvez affiner la liste à l’aide du filtre de date.
     

---

Catalogue d’événements

Le Catalogue d’événements peut être considéré comme la documentation svix intégrée pour l’intégration webhook, qui fournit des informations à jour sur les types d’événements, leurs schémas et des exemples.

Cliquez sur l’onglet Catalogue d’événements. Il liste et décrit tous les types d’événements que nous proposons.

Types d’événements

Cliquez sur un type d’événement pour afficher son contenu. Vous pouvez consulter son schéma et un exemple de payload JSON.

Actuellement, Dryad propose trois types d’événements :

alert-event.new

Un nouveau relevé de gaz pertinent a été reçu dans le cadre d’une alerte active.

Exemple :

{
 "alert": "https://dryad.app/fr/alert-center/63a6a704-5a7a-4d43-9716-10de0d7cc182",
 "confidence_level": 0.89,
 "datetime": "2024-04-30T18:10:00.000Z",
 "device": {
   "coordinates": {
     "coordinates": [
       13.404954,
       52.520008
     ],
     "type": "Point"
   },
   "eui": "CC1BAA0010000025",
   "name": "SN 12571"
 },
 "severity": "alert",
 "urn": "urn:forestfloor:alert-event:84382a41-f97f-441a-bb13-e141b2c4779b"
}

alert.new

Une nouvelle alerte incendie a été déclenchée.

Exemple :

{
  "datetime": "2024-04-30T18:10:00.000Z",
  "site": {
    "name": "Si Berlin était une forêt",
    "url": "https://dryad.app/fr/sites/999",
    "urn": "urn:forestfloor:site:baee084d-f6cf-45b0-8227-ac7bdad6ed49"
  },
  "url": "https://dryad.app/fr/alert-center/63a6a704-5a7a-4d43-9716-10de0d7cc182",
  "urn": "urn:forestfloor:alert:63a6a704-5a7a-4d43-9716-10de0d7cc182"
}

wf.measurement.new

Mesure environnementale reçue par le Wildfire Sensor.

Schéma :

Exemple :

{
  "air_pressure": 102331,
  "air_quality": 145,
  "datetime": "2024-04-30T18:10:00.000Z",
  "device": {
    "coordinates": {
      "coordinates": [
        13.404954,
        52.520008
      ],
      "type": "Point"
    },
    "eui": "CC1BAA0010000025",
    "name": "SN 12571"
  },
  "energy_level": 0.67,
  "humidity": 57,
  "site": {
    "name": "Si Berlin était une forêt",
    "url": "https://dryad.app/fr/sites/999",
    "urn": "urn:forestfloor:site:baee084d-f6cf-45b0-8227-ac7bdad6ed49"
  },
  "temperature": 18.4
}

---

Modifier un endpoint

Suivez les étapes ci-dessous si vous souhaitez mettre à jour l’URL du endpoint.

• Accédez à votre application et sélectionnez l’onglet Endpoints si ce n’est pas déjà fait. Sélectionnez ensuite le Endpoint que vous souhaitez modifier dans la liste des Endpoints. Cela affichera la section de configuration du Endpoint.
  

• Cliquez sur le bouton Modifier à côté de l’URL du endpoint existant.

  

• Remplacez l’URL du endpoint existant par la nouvelle URL du endpoint.
• Cliquez sur le bouton Enregistrer

---

Modifier les événements abonnés

Avec votre application, vous pouvez modifier à tout moment les événements auxquels vous êtes abonné sur chaque endpoint.

• Accédez à votre application et sélectionnez l’onglet Endpoints si ce n’est pas déjà fait. Sélectionnez ensuite le Endpoint pour lequel vous souhaitez modifier les événements abonnés. Cela affichera la section de configuration du Endpoint.
• Dans le panneau de droite, sous la section Événements abonnés, vous pouvez voir à quels événements vous êtes abonné pour ce endpoint.
• Cliquez sur le bouton Modifier.

• Cochez ou décochez les types d’événements auxquels vous souhaitez vous abonner ou vous désabonner.
• Cliquez sur le bouton Enregistrer

---

Tester les endpoints

Cette fonctionnalité vous permet de tester votre endpoint pour vérifier s’il reçoit bien les messages.

Accédez à votre application et sélectionnez l’onglet Endpoints si ce n’est pas déjà fait. Sélectionnez ensuite le Endpoint que vous souhaitez tester. Cela affichera la section de configuration du Endpoint.

• Allez dans l’onglet Test.
• Sélectionnez un type d’événement dans la liste déroulante à tester.

• Une fois le type d’événement sélectionné, son schéma s’affichera sur la page avec un exemple de payload JSON pour vous montrer les champs envoyés dans le message.
• Cliquez sur le bouton Envoyer l’exemple pour envoyer le message.

Après l’envoi d’un message pour un événement, si cela fonctionne, vous pourrez le voir dans l’onglet Vue d’ensemble.

 ---

Désactiver un endpoint

Accédez à votre application et sélectionnez l’onglet Endpoints, si ce n’est pas déjà fait. Sélectionnez ensuite le Endpoint que vous souhaitez désactiver. Cela affichera la section de configuration du Endpoint.

Désactiver un endpoint empêchera l’envoi de messages vers ce endpoint.

• Dans le menu en haut à droite , cliquez sur Désactiver le endpoint.

• Une fois désactivé, une étiquette Désactivé apparaîtra sur la page du endpoint, comme ci-dessous.

Pour réactiver le endpoint, cliquez sur Activer le endpoint dans le même menu.

 ---

Supprimer un endpoint

Accédez à votre application et sélectionnez l’onglet Endpoints, si ce n’est pas déjà fait. Sélectionnez ensuite le Endpoint que vous souhaitez supprimer. Cela affichera la section de configuration du Endpoint.

Dans le menu en haut à droite , cliquez sur Supprimer. Cela supprimera définitivement le endpoint de votre application et cette action est irréversible.