Einen Slack-Kanal über die API verbinden¶

Diese Seite richtet sich an Administratoren, die Benachrichtigungen über ihre Organisation in einem Slack-Kanal erhalten möchten. Sie zeigt, wie Sie einen Kanal verbinden, was eine Nachricht sagt, wie Sie testen und was Sie tun, wenn Slack nichts mehr empfängt. Wie Sie eine Anfrage an OS stellen (Adresse, Anmeldung, Seiten, Fehler), steht unter Die Zugriffs-API.

Bevor Sie beginnen¶

• Slack muss in dieser Umgebung eingeschaltet sein. Ist es ausgeschaltet, antwortet OS beim Verbinden, Ändern und Testen mit 409.
• Sie brauchen write auf notification_channel (Arten und Aktionen). Die Administratorrolle hat es, und es ist in jedem Dienst einer Organisation, welche Pläne sie auch hat.
• Legen Sie in Slack einen Incoming Webhook für den Kanal an (in Slack: eine App mit Incoming Webhooks, dann Add New Webhook to Workspace und den Kanal wählen). Slack gibt Ihnen eine Adresse, die mit https://hooks.slack.com/services/ beginnt.

Wer die Adresse hat, kann in diesem Kanal schreiben. OS speichert sie verschlüsselt und zeigt sie nie wieder, auch Ihnen nicht. Bewahren Sie sie nirgendwo sonst auf.

Verbinden¶

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 nennt die Arten von Benachrichtigungen, die in den Kanal gehen. Nur Arten, die die Organisation selbst betreffen, können in einen Kanal gehen: ein abgelaufener Plan (service.plan_lapsed), ein Webhook, der fehlschlägt oder ausgeschaltet wurde (events.webhook_failing, events.webhook_disabled) und ein Slack-Kanal, der nichts mehr empfängt (notifications.slack_failing). Nichts über Personen geht je nach Slack.
• locale ist nl, en, de, fr oder es; ohne Angabe Niederländisch.
• Eine Organisation verbindet standardmäßig höchstens fünf Kanäle.

Was eine Nachricht sagt¶

Im Slack-Kanal liest jeder mit, auch Personen, die in OS nicht zu Ihrer Organisation gehören. Eine Nachricht enthält deshalb nur: die Art der Benachrichtigung, wie das Benachrichtigungszentrum sie nennt (etwa „Ein Plan ist abgelaufen"), in der Sprache der Verbindung, den Namen der Organisation, höchstens ein Datum oder eine Zahl (bei einem abgelaufenen Plan: das Datum, an dem er endete) und einen Link in OS. Nie den Namen oder die Adresse einer Person, einen Betrag, den Namen eines Plans, den Namen eines Webhooks oder etwas, das jemand geschrieben hat.

Welche Kanäle eine Benachrichtigung erreicht: nur die Ihrer eigenen Organisation, und nur bei Benachrichtigungen über Ihre Organisation selbst. Der Kanal eines Partners erhält nie eine Benachrichtigung über einen seiner Kunden; die Administratoren des Partners lesen diese in OS und per E-Mail. Ein Kunde ohne eigenen Kanal erhält nichts in Slack.

Solange die Regeln Ihrer Organisation ein forbid auf notification_channel enthalten, postet OS nichts in einen ihrer Slack-Kanäle, auch nicht, was schon zum Posten bereitlag.

Testen, ändern, trennen¶

Ein Test erreicht den Kanal innerhalb von Sekunden. Ob er angekommen ist, zeigt last_delivered_at. Solange die Regeln Ihrer Organisation notification_channel verbieten, antwortet ein Test weiter mit 202, und es kommt nichts an.

Wenn Slack nichts mehr empfängt¶

• revoked: Slack sagte, der Webhook existiert nicht mehr, oder der Kanal wurde archiviert. Legen Sie in Slack einen neuen Webhook an und setzen Sie ihn mit PATCH auf die Verbindung; sie ist sofort wieder active.
• failing: Posts schlugen immer wieder fehl (standardmäßig fünfmal hintereinander). OS postet nichts mehr, bis Sie eine neue Adresse setzen oder einen Test senden, der ankommt.

In beiden Fällen erhalten die Administratoren Ihrer Organisation eine Benachrichtigung in OS und per E-Mail, höchstens einmal pro Woche und Verbindung. Jede Änderung steht im Prüfprotokoll, ohne die Adresse.

Wohin die Nachrichten gehen¶

Slack ist ein Dienst von Slack Technologies in den Vereinigten Staaten. OS sendet nur den oben beschriebenen Inhalt, und nur an die Kanäle, die Sie verbinden. Eine Organisation, die nichts in die Vereinigten Staaten senden darf, verbietet notification_channel in ihren Regeln.