Connecter un canal Slack par l'API¶

Cette page s'adresse aux administrateurs qui veulent recevoir dans un canal Slack des notifications sur leur organisation. Elle montre comment connecter un canal, ce que dit un message, comment tester et que faire quand Slack ne reçoit plus rien. Comment faire une requête à OS (adresse, connexion, pages, erreurs) est expliqué dans L'API d'accès.

Avant de commencer¶

• Slack doit être activé dans cet environnement. S'il est désactivé, OS répond 409 à la connexion, à la modification et au test.
• Il vous faut write sur notification_channel (Types et actions). Le rôle d'administrateur l'a, et il fait partie du service de chaque organisation, quelles que soient ses offres.
• Dans Slack, créez un incoming webhook pour le canal (dans Slack : une application avec Incoming Webhooks, puis Add New Webhook to Workspace et choisissez le canal). Slack vous donne une adresse qui commence par https://hooks.slack.com/services/.

Qui a l'adresse peut écrire dans ce canal. OS la garde chiffrée et ne la montre plus jamais, pas même à vous. Ne la conservez nulle part ailleurs.

Connecter¶

curl -s -X POST "$OS/api/v1/organisations/$ORG/slack-webhooks" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.slack.com/services/T.../B.../...", "label": "#ops",
       "kinds": ["service.plan_lapsed"], "locale": "en"}'

{"id": "swh_...", "label": "#ops", "kinds": ["service.plan_lapsed"], "locale": "en",
 "state": "active", "consecutive_failures": 0, "last_delivered_at": null,
 "allowed_actions": ["see", "write", "delete"]}

• kinds nomme les sortes de notifications qui vont au canal. Seules les sortes qui concernent l'organisation elle-même peuvent aller à un canal : une offre arrivée à échéance (service.plan_lapsed), un webhook qui échoue ou a été désactivé (events.webhook_failing, events.webhook_disabled) et un canal Slack qui ne reçoit plus rien (notifications.slack_failing). Rien sur des personnes ne va jamais dans Slack.
• locale vaut nl, en, de, fr ou es ; sans elle, le néerlandais.
• Une organisation connecte au plus cinq canaux par défaut.

Ce que dit un message¶

Tout le monde dans le canal Slack lit les messages, y compris des personnes qui ne sont pas membres de votre organisation dans OS. Un message ne contient donc que : la sorte de notification telle que le centre de notifications la nomme (par exemple « Une offre est arrivée à échéance »), dans la langue de la connexion, le nom de l'organisation, au plus une date ou un nombre (pour une offre arrivée à échéance : la date de sa fin) et un lien vers OS. Jamais le nom ou l'adresse d'une personne, un montant, le nom d'une offre, le nom d'un webhook ni rien de ce que quelqu'un a écrit.

Quels canaux une notification atteint : seulement ceux de votre propre organisation, et seulement pour les notifications sur votre organisation elle-même. Le canal d'un partenaire ne reçoit jamais de notification sur l'un de ses clients ; les administrateurs du partenaire les lisent dans OS et par e-mail. Un client sans canal à lui ne reçoit rien dans Slack.

Tant que les règles de votre organisation contiennent un forbid sur notification_channel, OS ne poste rien dans aucun de ses canaux Slack, pas même ce qui attendait déjà d'être posté.

Tester, modifier, déconnecter¶

Un test atteint le canal en quelques secondes. S'il est arrivé, last_delivered_at le montre. Tant que les règles de votre organisation interdisent notification_channel, un test répond quand même 202 et rien n'arrive.

Quand Slack ne reçoit plus rien¶

• revoked : Slack a dit que le webhook n'existe plus, ou que le canal a été archivé. Créez un nouveau webhook dans Slack et mettez-le sur la connexion avec PATCH ; elle redevient aussitôt active.
• failing : les envois ont échoué à répétition (cinq fois de suite par défaut). OS ne poste plus rien tant que vous n'avez pas mis une nouvelle adresse ou envoyé un test qui arrive.

Dans les deux cas, les administrateurs de votre organisation reçoivent une notification dans OS et par e-mail, au plus une fois par semaine et par connexion. Chaque changement figure dans le journal d'audit, sans l'adresse.

Où vont les messages¶

Slack est un service de Slack Technologies aux États-Unis. OS n'envoie que le contenu décrit plus haut, et seulement aux canaux que vous connectez. Une organisation qui ne peut rien envoyer aux États-Unis interdit notification_channel dans ses règles.