technique:adminserv:mattermost:hooks_commands

Gérer les intégrations

Par intégration, on entend les interactions entre Mattermost et d’autres applications.

Deux fonctionnalités méconnues de Mattermost sont la création de hooks entrants et de commandes slash.

  • Un hook entrant (abrévié hook par la suite) est une URL spéciale qui permet de poster un message sur un canal particulier lorsque l’URL est requêtée.
  • Une commande slash (abrévié commande par la suite) est un mot clé précédé d’un symbole / qui déclenche l’appel à une URL externe et remplace le commande par la réponse de l’URL.

Les commandes sont à différencier des commandes de plugin (comme /spoiler), qui ne requêtent pas nécessairement une URL extérieure.

Note:

Les hooks sont très pratiques pour réagir à un événement extérieur et poster un message suite à cet événement. Voici quelques exemples :

  • Ajout d’une nouvelle tâche sur un kanban : un message est posté sur le canal concerné
  • Ouverture d’une nouvelle issue sur Gitlab : une mention est envoyée aux membres du dépôt
  • CPU au dessus de 80% sur une des machines virtuelles : une mention est envoyée à l’équipe technique.

Attention:

Les hooks ne fonctionnent qu’avec des outils “compatibles” Slack ou Mattermost.

Note:

Les commandes slash sont utiles pour déclencher une action extérieure ou générer un message contenant une information dynamique. Exemples :

  • Obtenir les statistiques d’un service, les mettre en forme et les poster
  • Déclencher la génération d’un rapport journalier quelconque
  • Générer et poster une citation d’un personnage de Kaamelott

Pour résumer, les hooks permettent d’être informés d’un événement, les commandes permettent de déclencher un événement ou de générer des informations dynamiques.

Les hooks et les commandes sont circonscrits à une seule équipe. Une commande mise en place sur une équipe ne fonctionnera que sur cette équipe.

Les administrateurs d’équipes sont les seules personnes à pouvoir gérer les hooks et commandes. Ceci étant, c’est très pratique car il n’y a pas besoin d’un administrateur système pour créer ses propres commandes/hooks.

La personne qui crée une équipe en est automatiquement administrateur, et peut ensuite étendre ce rôle aux autres membres depuis la gestion des membres de l’équipe. La plupart des personnes ne sont pas au courant de ce rôle, il ne faut pas hésiter à leur signaler si ça peut être utile. :)

La gestion des intégrations se fait depuis l’URL suivante, construite à partir du nom de l’équipe :

https://team.picasoft.net/<equipe>/integrations

Depuis les intégrations, ajouter un nouveau hook entrant. Voici un exemple de paramétrage :

Avec cette configuration, quiconque possède le lien du hook pourra poster dans le canal Tests, avec le nom d’utilisateur webhook et la photo de profil accessible à l’URL donnée.

Attention:

Il est recommandé de verrouiller le canal. En effet, le lien suffit pour poster des messages et est donc assez sensible. S’il permettait de poster n’importe où, on pourrait imaginer des situations d’usurpation assez problématiques.

Une URL confidentielle est générée suite à l’enregistrement du hook.

Cette URL peut maintenant être utilisée par une application compatible Slack ou Mattermost. Mais elle peut aussi être utilisée “à la main” ou dans un script personnalisé.

Pour ce faire, il suffit d’effectuer une requête POST sur l’URL, avec pour corps de la requête un objet JSON contenant a minima un champ text dont la valeur est le corps du message à poster sur le canal.

En reprenant l’exemple précédent, la commande suivante postera un message sur le canal Tests :

snippet.bash
$ curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "## Message formaté !!\nAvec retour à la ligne et mention @quentinduchemin :relaxed:"}' https://team.picasoft.net/hooks/sxdkzr7gotystkj5gmdmqt9ofy

Le message est en effet reçu, le formatage Markdown est interprété et les mentions envoient des notifications aux personnes concernées.

Côté console, on reçoit un 200 OK pour indiquer que tout s’est bien passé.

L’idée est de montrer le fonctionnement basique d’une commande.

On se rend dans les intégrations, onglet commandes slash, et on crée une commande, par exemple :

Les paramètres sont similaires au webhook entrant. En revanche, deux choix sont importants :

  • L’URL qui sera appelée lors du déclenchement de la commande,
  • La méthode (GET ou POST).

Le reste est de la responsabilité du serveur, qui reçoit toutes les informations de la commande et formate une réponse.

Dans tous les cas, le serveur distant doit répondre avec un objet JSON qui contient au moins l’attribut text, valeur du message à écrire en réponse à la commande.

Voici un exemple simplissime qui répond à toutes les requêtes POST en ajoutant dans la réponse les paramètres passés à la commande :

snippet.python
from flask import Flask, request
 
app = Flask(__name__)
 
 
@app.route('/', methods=['POST'])
def result():
    return {
        "text": f"## Commande reçue!\nPayload : {request.form['text']}"
    }

Pour le tester, il suffit de l’enregistrer (par exemple simple_server.py), puis de lancer :

snippet.bash
$ pip install flask
$ FLASK_APP=simple_server.py flask run -h 0.0.0.0

L’application est accessible à l’URL de votre serveur sur le port 5000.

Important:

Ne jamais utiliser ce genre d’exemples en production! Le serveur de développement de Flask n’est à utiliser que pour des tests. De plus, HTTPS n’est pas activé, ce qui rend possible l’interception du jeton utilisé pour valider la réponse.

Important:

Dans un exemple réel, le serveur doit valider que le jeton reçu en paramètre de la requête (token) est le même que le jeton généré après l’ajout de la commande dans Mattermost. Cette vérification permet de valider que la requête vient bien de Mattermost, et pas d’un usurpateur qui pourrait vouloir récupérer des informations sensibles ou déclencher un processus non-souhaité.

Pour tester, il suffit de déclencher la commande dans n’importe quel canal de l’équipe :

/test_commande Voici les paramètres!

La commande est envoyée, et Mattermost affiche en réponse :

Note:

Par défaut, le message n’est visible que par la personne qui écrit la commande. Il est possible de changer ce comportement en assignant in_channel à l’attribut response_type dans l’objet JSON de la réponse.

Les commandes et les hooks sont très puissants. Dans leur forme basique, ils permettent de poster un message en réponse à un événement extérieur ou une commande depuis Mattermost.

En plus des exemples basiques vus ici (seul l’attribut text de la réponse est utilisé), il existe des options avancées de formatage, de redirection, de réponse délayée, de remplacement du nom d’utilisateur, etc.

Ces paramètres sont traités dans la documentation officielle.

  • technique/adminserv/mattermost/hooks_commands.txt
  • de qduchemi