diff --git a/integrations/alerts/slack.mdx b/integrations/alerts/slack.mdx index 5c9ddff0..f62aeed0 100644 --- a/integrations/alerts/slack.mdx +++ b/integrations/alerts/slack.mdx @@ -7,13 +7,19 @@ canonical: 'https://www.checklyhq.com/docs/integrations/alerts/slack/' Setting up Slack as an alerting channel is simple: -1. First, install the Checkly Slack App into your Slack Workspace by going to [your integrations page](https://app.checklyhq.com/accounts/settings/account/integrations) and click "Connect Slack Workspace". +1. First, install the Checkly Slack App into your Slack Workspace by going to [your integrations page](https://app.checklyhq.com/accounts/settings/account/integrations) and click **Connect Slack workspace**. 2. Then, head to [your alert settings](https://app.checklyhq.com/accounts/alerts/settings), click "Add more channels" and select a new Slack channel. ![Add a Slack WebHook URL to Checkly](/images/docs/images/alerting/slack.png) You can add any **#public-channel-name** or **@username** for Direct Messages. Each entry must start with `#` or `@`. For private channels, the Checkly Slack app needs to be explicitly invited to that channel by tagging it like `@Checkly`. +Checkly doesn't check `#` channel names when you save the alert channel. It does match each `@` entry to a person in your workspace, and refuses to save an entry it can't match. Select **Test alert channel** to send a test message to each entry. + +A Checkly account connects one Slack workspace at a time. Your integrations page shows it under **Connected workspace**. Connecting a different workspace replaces the current one. Alert channels with `@` entries then stop sending direct messages until you open each channel and save it again. + +To send alerts to a second Slack workspace, or to a workspace whose admins don't approve the Checkly app, use a [Slack incoming webhook](/integrations/alerts/webhooks#slack-incoming-webhook) with a Webhook alert channel instead. + If you're using a free Slack workspace, be aware of [message limits](https://slack.com/help/articles/115002422943-Usage-limits-for-free-workspaces). Exceeding these limits may prevent new alerts from being delivered. @@ -70,6 +76,38 @@ Checkly requests these Slack permissions for the Checkly Slack app to work withi | `links:read` | Read links for allow-listed domains like [app.checklyhq.com](http://app.checklyhq.com) to provide rich context | | `links:write` | Writes rich context for allow-listed domains like [app.checklyhq.com](http://app.checklyhq.com) | +Connecting a workspace grants all of these permissions together. To send alerts, Checkly posts messages (`chat:write`, `chat:write.public`) and looks up the people you send DMs to (`users:read`). + +## Troubleshooting + +### Test alert channel fails + +If a test message can't be posted, the error names the entry and the error Slack returned, for example `Failed to post to #alerts (channel_not_found)`. + +| Error | What to check | +| :-- | :-- | +| `channel_not_found` | The channel name is spelled correctly and the channel exists. For a private channel, invite the Checkly app to it first. | +| `is_archived` | The channel is archived. Unarchive it or choose another channel. | +| `unresolvable_handles` | Each `@` entry must match exactly one person in your workspace by Slack username, display name or full name. Checkly doesn't match guest accounts, and `@here`, `@channel` and `@everyone` aren't supported. | + +### The alert channel says the Slack app isn't installed + +If a Slack alert channel shows **The Checkly Slack app is not installed**, no Slack workspace is connected to your Checkly account, for example because the integration was removed. The alert channel is kept, but Checkly sends no alerts to it until you connect a workspace again on your integrations page. + +### The workspace doesn't show as connected + +**Connect Slack workspace** opens Slack in a popup. After you approve the app, the popup closes and your integrations page shows the workspace under **Connected workspace**. Checkly saves the connection only when the popup reports back to the Checkly page that opened it, so keep that page open until the popup closes. If Slack returns an error or you cancel, Checkly reports it, for example `Slack OAuth denied: access_denied`, and nothing is connected. Select **Connect Slack workspace** to try again. + +### Alerts don't arrive + +If the test message arrives but alerts don't, check that: + +- the check is subscribed to the alert channel, in the channel's **Subscriptions** section; +- the alert channel notifies for that event, under **Notification events**; +- the check changed state and met your alert threshold. Checkly sends alerts when a check changes state, not for every failed run. See [Testing your alerts](/communicate/alerts/overview#testing-your-alerts). + +The [alert notification log](/communicate/alerts/notification-log) shows the Slack deliveries that failed. + ## Privacy Policy For information about how Checkly collects, uses, and protects your data, see our [Privacy Policy](https://checklyhq.com/privacy). \ No newline at end of file diff --git a/integrations/alerts/webhooks.mdx b/integrations/alerts/webhooks.mdx index f4d4fb78..c025db38 100644 --- a/integrations/alerts/webhooks.mdx +++ b/integrations/alerts/webhooks.mdx @@ -372,6 +372,28 @@ Send a message using [Pushover](https://pushover.net/) by posting this body: } ``` +### Slack incoming webhook + +To send alerts to a Slack workspace that isn't connected to your Checkly account, for example a second workspace or one where the [Checkly Slack app](/integrations/alerts/slack) isn't approved, post them to an incoming webhook of a Slack app you create. This uses a generic **Webhook** alert channel, not the deprecated **Slack webhook** alert channel: + +1. In Slack, create an app in the workspace, turn on **Incoming Webhooks**, select **Add New Webhook to Workspace** and pick the channel. Copy the webhook URL. See Slack's guide to [sending messages using incoming webhooks](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks). Depending on your workspace's settings, installing the app can need an admin's approval. +2. In Checkly, add a **Webhook** alert channel with the method `POST` and the webhook URL as the URL. +3. Use a body with a `text` field, for example: + + ```json + { + "text": "{{{ALERT_TITLE}}}\n{{{RESULT_LINK}}}" + } + ``` + +The triple braces stop quotes in the check name, and `&` or `=` in the link, from being HTML-escaped. See [Using Variables](#using-variables). + +Compared to the Checkly Slack app: + +- Each webhook URL posts to the one channel you picked when you created it. To alert another channel, create another webhook and another alert channel. +- Each alert is posted as a new message. +- The message contains only what your body template includes. You write the message format yourself. + ### Trello You can create a [Trello](https://trello.com) card using just the URL and no payload: