From df677d5da7698c9f8f039413bdf02100e23bceb7 Mon Sep 17 00:00:00 2001 From: Hannes Lenke Date: Sat, 7 Nov 2026 22:27:34 -0500 Subject: [PATCH 1/6] docs: Slack troubleshooting, one workspace per account, and what alerts use Add a Troubleshooting section to the Slack page (test errors, the app-not-installed warning, connecting the workspace, alerts that don't arrive), say that an account connects one Slack workspace at a time, that channel names aren't checked on save, and which permissions sending alerts uses. Match the button label in the UI. Co-Authored-By: Claude Opus 5.5 --- integrations/alerts/slack.mdx | 38 ++++++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/integrations/alerts/slack.mdx b/integrations/alerts/slack.mdx index 5c9ddff0d..d054134a3 100644 --- a/integrations/alerts/slack.mdx +++ b/integrations/alerts/slack.mdx @@ -7,13 +7,17 @@ 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. 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. + 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 +74,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 From c7b1be02d3939252b4a22010a2bb8ec9ffbff3ca Mon Sep 17 00:00:00 2001 From: Hannes Lenke Date: Sun, 8 Nov 2026 19:30:39 -0500 Subject: [PATCH 2/6] docs(alerts): document the Slack incoming-webhook fallback on the webhooks page Adds a short how-to and its limits to the webhook examples and links it from the Slack page for a second workspace or an unapproved Checkly app. Co-Authored-By: Claude Opus 5.5 --- integrations/alerts/slack.mdx | 2 ++ integrations/alerts/webhooks.mdx | 22 ++++++++++++++++++++++ 2 files changed, 24 insertions(+) diff --git a/integrations/alerts/slack.mdx b/integrations/alerts/slack.mdx index d054134a3..4da54981a 100644 --- a/integrations/alerts/slack.mdx +++ b/integrations/alerts/slack.mdx @@ -18,6 +18,8 @@ Checkly doesn't check channel names when you save the alert channel. Select **Te 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. +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. diff --git a/integrations/alerts/webhooks.mdx b/integrations/alerts/webhooks.mdx index f4d4fb787..0b1365679 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 a Slack incoming webhook: + +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: From 0783bc1b22290c44bdb89a27c4575578762ba62d Mon Sep 17 00:00:00 2001 From: Hannes Lenke Date: Tue, 10 Nov 2026 21:57:02 -0500 Subject: [PATCH 3/6] Apply suggestion from @hlenke --- integrations/alerts/slack.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/integrations/alerts/slack.mdx b/integrations/alerts/slack.mdx index 4da54981a..1936a9234 100644 --- a/integrations/alerts/slack.mdx +++ b/integrations/alerts/slack.mdx @@ -7,7 +7,7 @@ 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) From 65a2a1adbff60bd37df3d76ab36ed2731f5894f4 Mon Sep 17 00:00:00 2001 From: Hannes Lenke Date: Tue, 10 Nov 2026 21:58:10 -0500 Subject: [PATCH 4/6] Apply suggestion from @hlenke --- integrations/alerts/slack.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/integrations/alerts/slack.mdx b/integrations/alerts/slack.mdx index 1936a9234..1e804f736 100644 --- a/integrations/alerts/slack.mdx +++ b/integrations/alerts/slack.mdx @@ -14,7 +14,7 @@ Setting up Slack as an alerting channel is simple: 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. Select **Test alert channel** to send a test message to each entry. +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. From 33c07738808350233d21f1354c82663def2c396d Mon Sep 17 00:00:00 2001 From: Hannes Lenke Date: Tue, 10 Nov 2026 21:58:45 -0500 Subject: [PATCH 5/6] Apply suggestion from @hlenke --- integrations/alerts/slack.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/integrations/alerts/slack.mdx b/integrations/alerts/slack.mdx index 1e804f736..f62aeed0e 100644 --- a/integrations/alerts/slack.mdx +++ b/integrations/alerts/slack.mdx @@ -16,7 +16,7 @@ You can add any **#public-channel-name** or **@username** for Direct Messages. E 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. +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. From 9c5e1c802591eb1888ea7d1b41d4a54761c33d55 Mon Sep 17 00:00:00 2001 From: Hannes Lenke Date: Tue, 10 Nov 2026 21:59:23 -0500 Subject: [PATCH 6/6] Apply suggestion from @hlenke --- integrations/alerts/webhooks.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/integrations/alerts/webhooks.mdx b/integrations/alerts/webhooks.mdx index 0b1365679..c025db389 100644 --- a/integrations/alerts/webhooks.mdx +++ b/integrations/alerts/webhooks.mdx @@ -374,7 +374,7 @@ 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 a 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.