Een Slack-kanaal koppelen via de API¶

Deze pagina is voor beheerders die meldingen over hun organisatie in een Slack-kanaal willen zien. Ze laat zien hoe je een kanaal koppelt, wat er in een bericht staat, hoe je test en wat je doet als Slack niets meer ontvangt. Hoe je een verzoek aan OS doet (adres, aanmelden, pagina's, fouten), staat in De access-API.

Voordat je begint¶

• Slack moet in deze omgeving aan staan. Staat het uit, dan antwoordt OS 409 op koppelen, wijzigen en testen.
• Je hebt write nodig op notification_channel (Soorten en acties). De beheerdersrol heeft dat, en het zit in de dienst van elke organisatie, welke pakketten ze ook heeft.
• Maak in Slack een incoming webhook voor het kanaal (in Slack: een app met Incoming Webhooks, dan Add New Webhook to Workspace en het kanaal kiezen). Slack geeft je een adres dat begint met https://hooks.slack.com/services/.

Wie het adres heeft, kan in dat kanaal schrijven. OS bewaart het versleuteld en toont het nooit meer, ook niet aan jou. Zet het nergens anders neer.

Koppelen¶

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": "#beheer",
       "kinds": ["service.plan_lapsed"], "locale": "nl"}'

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

• kinds noemt de soorten meldingen die in het kanaal komen. Alleen soorten over de organisatie zelf kunnen naar een kanaal: een abonnement dat is afgelopen (service.plan_lapsed), een webhook die faalt of is uitgeschakeld (events.webhook_failing, events.webhook_disabled) en een Slack-kanaal dat niets meer ontvangt (notifications.slack_failing). Over mensen gaat er nooit iets naar Slack.
• locale is nl, en, de, fr of es; zonder is het Nederlands.
• Een organisatie koppelt standaard ten hoogste vijf kanalen.

Wat er in een bericht staat¶

Iedereen in het Slack-kanaal leest mee, ook wie geen lid van je organisatie in OS is. Daarom staat er in een bericht alleen: de soort melding zoals het meldingencentrum die noemt (zoals "Een abonnement is afgelopen"), in de taal van de koppeling, de naam van de organisatie, hoogstens één datum of aantal (bij een afgelopen abonnement: de datum waarop het afliep) en een link naar OS. Nooit de naam of het adres van een persoon, een bedrag, de naam van een abonnement, de naam van een webhook of iets wat iemand schreef.

Welke kanalen een melding krijgt: alleen die van je eigen organisatie, en alleen voor meldingen over je organisatie zelf. Het kanaal van een partner krijgt nooit een melding over een van zijn klanten; de beheerders van de partner lezen die in OS en per mail. Een klant zonder eigen kanaal krijgt niets in Slack.

Zolang de regels van je organisatie een forbid op notification_channel bevatten, plaatst OS niets in haar Slack-kanalen, ook niet wat al klaarstond.

Testen, wijzigen, ontkoppelen¶

Een test komt binnen enkele seconden in het kanaal. Of hij aankwam, zie je aan last_delivered_at. Zolang de regels van je organisatie notification_channel verbieden, antwoordt een test nog steeds 202 en komt er niets aan.

Als Slack niets meer ontvangt¶

• revoked: Slack zei dat de webhook niet meer bestaat, of het kanaal is gearchiveerd. Maak in Slack een nieuwe webhook en zet die met PATCH op de koppeling; ze is dan meteen weer active.
• failing: berichten bleven mislukken (standaard vijf keer achter elkaar). OS plaatst niets meer tot je een nieuw adres zet of een test stuurt die aankomt.

In beide gevallen krijgen de beheerders van je organisatie een melding in OS en per mail, hoogstens één keer per week per koppeling. Elke wijziging staat in het auditlog, zonder het adres.

Waar de berichten heen gaan¶

Slack is een dienst van Slack Technologies in de Verenigde Staten. OS stuurt alleen de inhoud hierboven, en alleen naar de kanalen die je koppelt. Een organisatie die niets naar de Verenigde Staten mag sturen, verbiedt notification_channel in haar regels.