Webhooks

Les webhooks permettent de notifier au destinataire préconfiguré les événements sur le portail à l'aide de liens de rappel http/https. Un utilisateur peut configurer les webhooks pour que les événements sur le portail 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 DocSpace.

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

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

Une fois le point de terminaison créé et configuré, vous pouvez créer des webhooks dans DocSpace. 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 (Salles, Documents).
   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 DocSpace à 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 sur le portail.
   • 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, vous pouvez la réinitialiser, mais il faudra mettre à jour toutes les applications d'intégration utilisant cette clé.
   • 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 du portail tels que Utilisateurs, Groupes, Documents, Dossiers et Salles. 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 DocSpace ou uniquement à l'événement déclencheur / plusieurs déclencheurs. Les notifications d'événements DocSpace 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 soumis à la modification.

Vous pouvez désactiver ou réactiver un webhook en utilisant le commutateur à côté. Utilisez l'icône à droite pour modifier les paramètres du webhook que vous avez indiqués lors de la création, afficher l'historique du webhook ou supprimer le 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.
• Événement déclencheur — 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.

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 DocSpace API, veuillez visiter api.onlyoffice.com.