Repository navigation
Slack: troubleshooting, one workspace per account, and what alerts use - #811
Conversation
…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>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 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
left a comment
There was a problem hiding this comment.
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
e0e0277fforintegrations/alerts/slack.mdxandintegrations/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/mainon both files: no commits.pr_impact.py: no broken anchors or links;webhooks.mdxis a hub page (26 inbound), and no existing anchors change. The new#slack-incoming-webhookanchor matches the new heading, and/communicate/alerts/overview#testing-your-alertsexists onmain.- Overlap:
gh pr list --json number,files, andgit merge-tree --write-treeof 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.vueandPageAlertChannelBuilder.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: …andSlack 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,@everyonereserved):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 withhandle_workspace_mismatchuntil they're resolved again:postAlertMessageinSlackIntegrationService.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.
- UI labels Connect Slack workspace and Connected workspace:
- 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).
Affected Components
What changed
integrations/alerts/slack.mdxchat:write,chat:write.publicandusers:read(for DM handles).channel_not_found,is_archived,unresolvable_handles) and what to check;integrations/alerts/webhooks.mdxtextbody, 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-treeof 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.is_archivedand other Slack errors@entries must match one person by username, display name or full name; guests,@here/@channel/@everyonerefusedunresolvable_handles(UI toast shows that code)#or@chat:write,chat:write.public,users:readchat.postMessage, andusers.listfor@entries; method scopes per Slack's API referenceerror=access_deniedand with a code Slack refuses{"text": …}as JSON)Webhook.sendMessage, monorepoorigin/main796988bcda)POSTis the methodWebhook.buildPayload); default methodPOST{"text": …}, with quotes and&/=intact under triple bracesbuildPayload/escapeJsonStringExpressionsfromorigin/mainwith Handlebars 4.7:{"text":"Check \"My API check\" has failed\nhttps://…?a=1&b=2"}; with double braces Handlebars outputs",&,=application/jsonNot tested, or left out
channel_not_foundfor 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.@handleDMs after switching workspace.🤖 Generated with Claude Code