Webhooks

Introduction

Les webhooks permettent de notifier au destinataire préconfiguré les événements dans l'espace de travail à l'aide de liens de rappel http/https. Un utilisateur peut configurer les webhooks pour que les événements dans l'espace de travail puissent déclencher des actions dans des services externes. Cette méthode peut être utile pour synchroniser et suivre certains événements.

Utilisez les webhooks pour effectuer des opérations personnalisées côté application ou site web que vous utilisez en fonction de différents événements sur ONLYOFFICE Apps.

Vous pouvez créer et gérer tous vos webhooks, les configurer et parcourir l'historique de chaque webhook pour vérifier leur rendement.

Créer un nouveau webhook

Premièrement, il faut configurer le point de terminaison pour webhooks au sein du service externe. Le point de terminaison sert à écouter des webhooks de l'espace de travail et recevoir des notifications d'événement.

Une fois le point de terminaison créé et configuré, vous pouvez créer des webhooks dans l'espace de travail. Pour créer un nouveau webhook,

1. Accédez à la section Outils de développement en cliquant sur Outils de développement sur le volet gauche d'une section (Fichiers, Salles, Formulaires).

   remarque

   Par défaut, l'accès à la section Outils de développement est activé pour tous les utilisateurs, sauf pour les invités, pour que tout utilisateur puisse accéder à cette page et, en conséquence, créer leurs propres webhooks. Les administrateurs peuvent afficher tous les webhooks, tandis que les utilisateurs peuvent afficher uniquement leurs propres webhooks.

   Pour les administrateurs, la section Outils de développement est accessible depuis le volet gauche et depuis les Paramètres de l'espace de travail à l'aide du menu dans le coin inférieur gauche en sélectionnant l'option Paramètres -> Outils de développement.

2. Dans Outils de développement, passez à la rubrique Webhooks.

3. Cliquez sur le bouton Créer un webhook.

4. Configurez les paramètres nécessaires :

   

   • Nom du webhook — un nom identifiant pour faciliter le travail avec le webhook dans l'espace de travail.

   • URL de charge utile — l'adresse du point de terminaison sur laquelle le webhook doit être envoyé.

   • Clé secrète — indiquez le secret du webhook permettant de vérifier les requêtes envoyées vers l'URL de charge utile. Saisissez votre clé ou cliquez sur Générer. Remarque : une fois la clé sauvegardée, il sera impossible de la récupérer. Si la clé secrète est oubliée ou perdue, ouvrez les paramètres du webhook et cliquez sur le lien Réinitialiser la clé pour en générer une nouvelle. Il faudra mettre à jour toutes les applications d'intégration utilisant la clé précédente.

     

   • Vérification SSL — par défaut, cette option est activée pour vérifier les certificats SSL lors de la remise de la charge utile. Il n'est pas recommandé de désactiver ce paramètre.

   • Événement déclencheur — utilisez l'option Tout envoyer ou cochez le bouton radio Événements individuels pour sélectionner certains déclencheurs, c'est-à-dire les événements relatifs aux modifications des composants de l'espace de travail tels que Utilisateurs, Groupes, Fichiers, Dossiers, Salles, Formulaires et Agents IA. Par exemple, utilisateur créé, invité, mis à jour, supprimé, etc.

   • ID de la cible — l'identificateur de l'utilisateur, du groupe, du fichier ou du dossier permettant de suivre les modifications d'un élément.

   

5. L'URL de charge utile doit répondre avec le code de statut 200 à une requête http avec la méthode HEAD.

6. Cliquez sur le bouton Créer.

En fonction de la configuration, le webhook sera attribué à tous les événements de l'espace de travail ou uniquement à l'événement déclencheur/plusieurs déclencheurs. Les notifications d'événements de l'espace de travail seront envoyées automatiquement vers le service externe. Les déclencheurs sélectionnés lors de la création d'un webhook sont déclenchés uniquement si le propriétaire du webhook est doté des autorisations d'accès appropriées au composant de l'espace de travail soumis à la modification.

Gérer les webhooks

Les webhooks créés sont affichés avec leur nom, leur auteur, l'URL de charge utile et leur état. Vous pouvez désactiver ou réactiver un webhook en utilisant le commutateur dans la colonne État. Utilisez l'icône à droite pour ouvrir le menu contextuel avec les options suivantes :

• Paramètres — modifiez les paramètres du webhook que vous avez indiqués lors de la création.
• Historique du webhook — affichez l'historique de livraison du webhook.
• Supprimer le webhook — supprimez le webhook.

Cliquez sur le webhook pour afficher l'historique du webhook

Lorsque vous affichez l'historique, vous pouvez filtrer des webhooks par date de livraison ou statut (N'est pas envoyé, 2XX, 3XX, 4XX, 5XX). Cliquez sur le bouton filtre , sélectionnez les paramètres nécessaires et cliquez sur Appliquer.

Vous pouvez sélectionner un ou plusieurs webhooks de la liste et utilisez l'option Réessayer qui s'affiche en haut pour redélivrer les webhooks sélectionnés. Ou cliquez sur l'icône à côté du webhook et sélectionnez l'option Réessayer dans le menu contextuel.

Cliquez sur l'icône à côté du webhook et sélectionnez l'option Détails du webhook dans le menu contextuel.

Les détails suivants sont disponibles :

• Statut — le statut d'une réponse.
• ID d'événement — l'identifiant de l'événement.
• Type d'événement — l'événement qui déclenche l'activation du webhook.
• Heure de l'événement — la date à laquelle l'événement s'est produit.
• Date de livraison — la date à laquelle la réponse a été reçue du point de terminaison.

Dans la section Demande/Réponse, vous pouvez également afficher l'en-tête de la requête POST, le corps de la requête POST, l'en-tête de la réponse POST et le corps de la réponse POST. Utilisez l'icône pour copier l'en-tête ou le corps de la demande ou de la réponse dans le presse-papiers.

Utilisez l'icône à côté de l'inscription Détails du webhook pour redélivrer le webhook.

Détails techniques

Les deux services qui sont utilisés sont les suivants :

1. ASC.Web.Studio fournit des méthodes pour envoyer des webhooks et lance WorkerService.

   WorkerService — permet de s'abonner pour recevoir des messages à partir du répartiteur (par exemple, RabbitMQ utilisé par défaut) qui sauvegarde les informations sur les envois en attente. Les messages à partir du répartiteur sont mis dans la file d'attente, et ensuite les demandes d'envoi des webhooks sont constamment envoyées vers cette file d'attente et établissent une communication asynchrone avec ASC.Webhooks.Service pour envoyer des webhooks.

2. ASC.Webhooks.Core fournit des méthodes pour publier des webhooks dans la base de données et le répartiteur de messages, ainsi que des méthodes pour travailler avec la base de données.

Pour en savoir plus sur ONLYOFFICE Apps API, veuillez visiter api.onlyoffice.com.