Connecting a Slack channel through the API¶

This page is for administrators who want notifications about their organisation in a Slack channel. It shows how to connect a channel, what a message says, how to test and what to do when Slack receives nothing more. How to make a request to OS (address, sign-in, pages, errors) is in The access API.

Before you start¶

• Slack must be on in this environment. When it is off, OS answers 409 to connecting, changing and testing.
• You need write on notification_channel (Kinds and actions). The administrator role holds it, and it is in every organisation's service, whatever its plans.
• In Slack, make an incoming webhook for the channel (in Slack: an app with Incoming Webhooks, then Add New Webhook to Workspace and pick the channel). Slack gives you an address starting with https://hooks.slack.com/services/.

Whoever has the address can write in that channel. OS keeps it encrypted and never shows it again, not even to you. Do not keep it anywhere else.

Connecting¶

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 names the kinds of notification that go to the channel. Only kinds about the organisation itself can go to a channel: a plan that ran out (service.plan_lapsed), a webhook that is failing or was disabled (events.webhook_failing, events.webhook_disabled) and a Slack channel that receives nothing more (notifications.slack_failing). Nothing about people ever goes to Slack.
• locale is nl, en, de, fr or es; without it, Dutch.
• An organisation connects at most five channels by default.

What a message says¶

Everyone in the Slack channel reads along, including people who are not members of your organisation in OS. So a message holds only: the kind of notification as the notification centre names it (such as "A plan ran out"), in the connection's language, the organisation's name, at most one date or count (for a plan that ran out: the date it ended) and a link into OS. Never a person's name or address, an amount, a plan's name, a webhook's name or anything someone wrote.

Which channels a notification reaches: only your organisation's own, and only for notifications about your organisation itself. A partner's channel never receives a notification about one of its customers; the partner's administrators read those in OS and by mail. A customer without a channel of its own gets nothing in Slack.

While your organisation's rules hold a forbid on notification_channel, OS posts nothing to any of its Slack channels, also what was already waiting to be posted.

Testing, changing, disconnecting¶

A test reaches the channel within seconds. Whether it arrived shows in last_delivered_at. While your organisation's rules forbid notification_channel, a test still answers 202 and nothing arrives.

When Slack receives nothing more¶

• revoked: Slack said the webhook no longer exists, or the channel was archived. Make a new webhook in Slack and set it on the connection with PATCH; it is active again at once.
• failing: posts kept failing (five times in a row by default). OS posts nothing more until you set a new address or send a test that arrives.

Either way your organisation's administrators get a notification in OS and by mail, at most once a week per connection. Every change is in the audit trail, without the address.

Where the messages go¶

Slack is a service of Slack Technologies in the United States. OS sends only the content above, and only to the channels you connect. An organisation that may send nothing to the United States forbids notification_channel in its rules.