Webhooks

Webhook permet de notifier au destinataire préconfiguré l'événement sur le portail à l'aide de liens de rappel http/https. Un utilisateur peut configurer les webhooks pour que le événements sur le portail puissent déclencher des actions dans des services externes. Cette méthode peut être utile pour syncroniser et suivre certains événements.

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

Vous pouvez créer et gérer tous 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ée pour tous les utilisateurs, sauf pour des invités pour que tout utilisateur peut accéder à cet page et, en conséquence, créer propres webhooks. Les administrateurs peuvent afficher tous les webhooks car 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 la section 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 Create webhook (Créer un webhook).
4. Configurez les paramètres nécessaires:
   
   • Webhook name (Nom de webhook) - un nom identifiant pour faciliter le travail avec le webhook sur le portail.
   • Payload URL (URL de charge utile) - l'adresse du point de terminaison sur laquelle le webhook doit être envoyé.
   • Secret key (Clé secrète) - indiquez le secret du webhook permettant de vérifier les requêtes envoyées vers l'URl de la charge utile. Saisissez votre clé ou cliquez sur Generate (Générer). Remarque: une fois la clé sauvegardée, il sera impossible de la récupérer. Si la clé privée est oubliée ou perdue, vous pouvez la réinitialiser mais on doit mettre à jour toutes les applications d'intégration protégées par cette clé.
   • SSL verification (Vévérification SSL) - par défaul, 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 Événements individuels pour sélectionner certains déclencheurs, ç-à-d 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. URL de la charge - la demande http HEAD doit entraîner la réponse avec le code statut 200.
6. Cliquez sur le bouton Create (Créer).

En fonction de la configuration, le webhook sera attribué à tous é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 curseur à côté. Utilisez l'icône à droite pour modifier les paramètres de webhook que vous avez indiqué 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 Apply (Appliquer).

Vous pouvez sélectionner un ou plusieurs webhooks de la liste et utilisez l'option Retry (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 Retry (Réessayer) dans le menu contextuel.

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

Les détails suivantes sont disponibles:

• Status (Statut) - le statut d'une réponse.
• Event ID (ID d'événement) - l'identifiant de l'événement.
• Trigger (Événement déclencheur) - l'événement qui déclenche l'activation du webhook.
• Event time (Heure de l'événement) - la date à laquelle l'événement s'est produit.
• Delivery time (Date de livraison) - la a date à laquelle le webhook a été envoyé vers le point de terminaison.

Dans la section Request/Response (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 requête POST. Utiliser l'icône pour copier l'en-tête/le corps de la demande ou de la réponse dans le presse-papiers.

Utilisez l'icône à côté de l'inscription Webhook details (Détails de webhook) pour relivrer 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és vers cette file d'attente et établit une communication asynchrone avec ASC.Webhoks.Service pour envoyer des webhooks.

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

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