Skip to content

Slack: troubleshooting, one workspace per account, and what alerts use - #811

Merged
hlenke merged 6 commits into
mainfrom
docs/slack-troubleshooting
Nov 11, 2026
Merged

hlenke merged 6 commits into
mainfrom
docs/slack-troubleshooting

Conversation

@hlenke

@hlenke hlenke commented Nov 8, 2026 •

Copy link
Copy Markdown
Member

Affected Components

  • Content & Marketing
  • Pricing
  • Test
  • Docs
  • Learn
  • Other

What changed

integrations/alerts/slack.mdx

  • Setup: Checkly doesn't check channel names on save, so use Test alert channel. An account connects one Slack workspace at a time, shown under Connected workspace; connecting another workspace replaces it.
  • Permissions: connecting grants all listed permissions together; sending alerts uses chat:write, chat:write.public and users:read (for DM handles).
  • New Troubleshooting section:
    • test errors (channel_not_found, is_archived, unresolvable_handles) and what to check;
    • the "The Checkly Slack app is not installed" warning on an alert channel;
    • a workspace that doesn't show as connected;
    • alerts that don't arrive although the test works (subscriptions, notification events, state changes), linking the existing testing and notification log docs.
  • The connect button label now matches the UI ("Connect Slack workspace").
  • One line pointing to a Slack incoming webhook for a second workspace, or a workspace whose admins don't approve the Checkly app.

integrations/alerts/webhooks.mdx

  • New Slack incoming webhook example (between Pushover and Trello): create the webhook in Slack, add a Webhook alert channel with that URL, a minimal text body, and its limits (one channel per webhook URL, each alert is a new message, you write the message format). It sits outside the sections docs(webhooks): which variables are filled, escaping, retries and dedup keys #817 edits; git merge-tree of the two branches is clean.

Why

People ask why Slack says a channel isn't found, why the test works but alerts don't, whether they can connect a second workspace, why connecting doesn't seem to stick, and why the app needs its permissions. The page covered setup and listed permissions, but had no troubleshooting.

How each claim was verified

Tested end to end on a local stack at monorepo main (e086a77755), through the web app and the internal API. Slack and the token store can't run locally, so their HTTP endpoints were replaced by a local stub in a scratch checkout (never committed). The stub answers like Slack's Web API; everything on the Checkly side (OAuth callback, finalize, storage, handle resolution, test endpoint, UI) ran unchanged.

Claim How it was verified Result
One workspace per account; connecting another replaces it Connected a second workspace through the OAuth flow; database and Integrations page Still one Slack integration (the table's key is account + type); UI shows only the second workspace under Connected workspace, with Remove integration and no connect button
Channel names aren't checked on save API: saved a Slack App channel with a channel name Slack doesn't know 200, saved
Test error names the entry and Slack's error UI: Test alert channel on that channel Toast "Test failed: Failed to post to #does-not-exist (channel_not_found)"; API 400 with the same message for is_archived and other Slack errors
@ entries must match one person by username, display name or full name; guests, @here/@channel/@everyone refused API test and save with handles; stub logs Display name resolved to the user ID and the DM was posted to it; unknown, ambiguous, guest and reserved handles → 400 unresolvable_handles (UI toast shows that code)
Entries must start with # or @ API save with a bare channel ID 400
Connecting grants all permissions together Install URL from the API One Slack authorize URL with all 15 listed scopes
Alerts use chat:write, chat:write.public, users:read Stub log of what Checkly calls when testing a channel and a DM chat.postMessage, and users.list for @ entries; method scopes per Slack's API reference
App-not-installed warning; channels kept; no alerts until reconnected Removed the integration (API), then opened the channel and the alert channel list Channel kept; UI shows "The Checkly Slack app is not installed … No alerts will be send to this channel …" and "No Slack app is installed" in the list
Connection is saved only when the popup reports back OAuth callback without the finalize call from the page Nothing stored until the page finalizes
Errors and cancel during connect OAuth callback with error=access_denied and with a code Slack refuses "Slack OAuth denied: access_denied" / "Slack OAuth exchange failed: …"; nothing stored
Subscriptions and Notification events sections UI on the Slack App channel page Both present
State changes, testing, notification log Existing pages (linked, unchanged) —
Slack incoming webhook setup steps; one fixed channel per webhook URL Slack's public guide Sending messages using incoming webhooks (the URL is tied to one channel; channel can't be overridden; body {"text": …} as JSON) —
Installing the app can need an admin's approval Slack help: Manage app approval for your workspace (internally developed apps are requested and approved) Worded as "depending on your workspace's settings"
Each alert is a new message Slack's guide: each POST to the webhook posts a message, and posted messages can't be deleted through the webhook. Checkly sends one request per alert (Webhook.sendMessage, monorepo origin/main 796988bcda) Nothing said about recovery messages
The message contains only the body template; POST is the method Code: with a template, the body is the rendered template (Webhook.buildPayload); default method POST —
The example body renders to valid JSON {"text": …}, with quotes and &/= intact under triple braces Ran the template through a verbatim copy of buildPayload/escapeJsonStringExpressions from origin/main with Handlebars 4.7: {"text":"Check \"My API check\" has failed\nhttps://…?a=1&b=2"}; with double braces Handlebars outputs ", &, = Valid JSON object, so it's sent as application/json

Not tested, or left out

  • What Slack itself returns (for example channel_not_found for a private channel the app hasn't joined) can't run locally. The table's advice follows Slack's API reference and this page's existing note about inviting the app to private channels.
  • Posting to a real Slack incoming webhook: no Slack workspace in the test setup. The Slack-side behavior comes from Slack's public docs.
  • Left out by decision: advice on Slack-side approval or network issues during connect, the in-app "App is not approved by Slack" notice, and @handle DMs after switching workspace.

🤖 Generated with Claude Code

…ts 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 <noreply@anthropic.com>
@mintlify

mintlify Bot commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
checkly-422f444a 🟢 Ready View Preview Nov 11, 2026, 2:59 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

…hooks 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 <noreply@anthropic.com>

@hlenke hlenke left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs changes · Most claims hold against the product source, but line 17 says Checkly doesn't check names on save, which is only true for # channels; fix that and the two other Important items, then it's ready.

CI is green, the PR is mergeable (CLEAN), and main hasn't touched slack.mdx or webhooks.mdx since the merge base.

Overlap with #817. Both PRs edit integrations/alerts/webhooks.mdx. This PR adds a section between Pushover and Trello; #817 edits the Using Variables, Handlebars, and Retries sections. git merge-tree of the two heads is clean, and neither PR depends on the other's text (the #using-variables anchor this PR links to already exists on main), so they can land in either order. #817's description says it has no overlap with this PR; that's not quite right, but there's no conflict.

Section placement. The new paragraphs sit right under the setup steps, and Troubleshooting goes after Permissions, before Privacy Policy. Both are good spots. The Slack incoming webhook example fits with the other third-party examples.

Inline: 3 Important, 1 Wording.

What I checked
  • Read the full diff from the merge base e0e0277f for integrations/alerts/slack.mdx and integrations/alerts/webhooks.mdx, plus both files at the PR head.
  • gh pr checks 811: all pass. gh pr view: MERGEABLE/CLEAN. git log <base>..origin/main on both files: no commits.
  • pr_impact.py: no broken anchors or links; webhooks.mdx is a hub page (26 inbound), and no existing anchors change. The new #slack-incoming-webhook anchor matches the new heading, and /communicate/alerts/overview#testing-your-alerts exists on main.
  • Overlap: gh pr list --json number,files, and git merge-tree --write-tree of PRs 811 and 817 (clean).
  • Local app unavailable (BUSY: someone's own Tilt is on the ports), so I verified against source instead. Monorepo origin/main@84921d2637:
    • UI labels Connect Slack workspace and Connected workspace: apps/webapp/src/pages/settings/account/integrations/SettingsAccountIntegrationsSlack.vue. Test alert channel, Notification events, Subscriptions: apps/webapp/src/pages/alert-channel-builder/PageAlertChannelBuilder.vue and PageAlertChannelBuilder.i18n.ts. The Checkly Slack app is not installed: apps/webapp/src/pages/alert-channel-builder/channels/configs/slack-app/SlackAppConfig.vue.
    • The test error format "Failed to post to ()" and per-entry delivery: apps/backend/api/src/common/services/slack/SlackIntegrationService.ts (sendTestMessage, postAlertMessage).
    • Slack OAuth denied: … and Slack OAuth exchange failed: …: apps/backend/api/src/modules/slack-integration/SlackIntegrationController.ts, SlackIntegrationService.ts.
    • Handle matching (username, then display name, then full name; deleted, bot, and guest members skipped; @here, @channel, @everyone reserved): apps/backend/api/src/common/services/slack/slack-handle-resolver.ts.
    • Handles are resolved when the channel is saved and when it's tested, and saving fails with unresolvable_handles: apps/backend/api/src/models/helpers/enric-slack-app-handles.ts. # entries pass through unchecked.
    • One integration per account: the Slack integration is read and removed by account and type in SlackIntegrationService.ts.
    • After a different workspace is connected, saved @ entries fail with handle_workspace_mismatch until they're resolved again: postAlertMessage in SlackIntegrationService.ts.
    • Webhook body handling for the Slack example (valid JSON is sent as an object; a JSON-string repair applies to expressions inside string literals; default method POST): apps/backend/api/src/common/services/alert-notification-service/channels/webhook/index.ts.
  • Slack incoming webhook behavior: the PR's citation of Slack's public guide (https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks). I didn't post to a real Slack webhook.
  • Could not verify: what Slack itself returns for each error code (only the Checkly side was traced).

Comment thread integrations/alerts/slack.mdx Resolved
Comment thread integrations/alerts/slack.mdx Resolved
Comment thread integrations/alerts/slack.mdx Resolved
Comment thread integrations/alerts/webhooks.mdx Resolved
@hlenke
hlenke merged commit 0d42887 into main Nov 11, 2026
7 checks passed
@hlenke
hlenke deleted the docs/slack-troubleshooting branch November 11, 2026 03:04

This branch was successfully deployed

1 active deployment
staging — 9c5e1c80 Deployed Nov 11, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant