Skip to content

Commit bb8976c

Browse files
cjanslowcjanslow
authored
add advanced slack custom message use case (#1262)
* add advanced slack custom message use case * add screenshots * trigger rebuild * remove extra file * Update site/content/docs/integrations/slack.md * Update site/content/docs/integrations/slack.md * Update site/content/docs/integrations/slack.md * Update site/content/docs/integrations/slack.md * Update site/content/docs/integrations/slack.md * Update site/content/docs/integrations/slack.md * Update site/content/docs/integrations/slack.md * Update site/content/docs/integrations/slack.md * Update site/content/docs/integrations/slack.md * Update site/content/docs/integrations/slack.md * Update site/content/docs/integrations/slack.md * Update site/content/docs/integrations/slack.md * Update site/content/docs/integrations/slack.md * Update site/content/docs/integrations/slack.md * Update site/content/docs/integrations/slack.md * Update site/content/docs/integrations/slack.md
1 parent 75972e0 commit bb8976c

File tree

5 files changed

+202
-0
lines changed

5 files changed

+202
-0
lines changed

‎site/assets/docs/images/alerting/slack-custom-degraded.png

176 KB
Loading

‎site/assets/docs/images/alerting/slack-custom-failed.png

248 KB
Loading

‎site/assets/docs/images/alerting/slack-custom-recovered-degraded.png

172 KB
Loading

‎site/assets/docs/images/alerting/slack-custom-recovered.png

172 KB
Loading

‎site/content/docs/integrations/slack.md

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,3 +33,205 @@ We provide a lot of information in the initial Slack message including links to
3333
From the recovered Slack message, you can see the timestamp as well as a link to the check itself.
3434

3535
![A slack message showing a recovered alert](/docs/images/alerting/slack-recovered-check.png)
36+
37+
38+
## Custom Slack Webhook Integration
39+
40+
For users who need more control over the Slack alert format and content, you can use a **Webhook Alert Channel** in Checkly to send fully customized messages to Slack.
41+
42+
This approach is ideal when the native Slack integration does not meet your formatting or dynamic content needs. You will be using a Webhook alert channel with a Slack Incoming WebHook URL and a custom payload template. This setup allows you to control Slack message formatting using Slack's [Block Kit](https://api.slack.com/block-kit).
43+
44+
### Steps
45+
46+
1. **Create a Slack Webhook**
47+
- [Create an Incoming WebHook integration](https://my.slack.com/services/new/incoming-webhook/) in Slack by selecting a default channel for your alerts. You’ll see a WebHook URL generated by Slack. Copy it.
48+
- Choose the bot name and icon for your alerts.
49+
50+
2. **Create a Webhook Alert Channel in Checkly**
51+
- Go to [Alert Settings > Add More Channels > Webhook](https://app.checklyhq.com/alerts/settings/channels/new/webhook)
52+
- Fill in the following:
53+
- **Name**: e.g. `Custom Slack Alerts`
54+
- **Method**: `POST`
55+
- **URL**: Paste the Slack Webhook URL
56+
- **Notification events**: Enable recovery, degraded, and failure. SSL expiry optional, but not supported in this template.
57+
- **Body**: See template below
58+
59+
3. **Customize the Template**
60+
61+
The following template uses conditional logic (`{{#if}}`) to change the message depending on the alert type:
62+
63+
``` {title="Body"}
64+
{
65+
"attachments": [
66+
{
67+
{{#if (eq ALERT_TYPE "ALERT_FAILURE")}}
68+
"color": "#a30200",
69+
{{/if}}
70+
{{#if (eq ALERT_TYPE "ALERT_RECOVERY")}}
71+
"color": "#2eb886",
72+
{{/if}}
73+
{{#if (eq ALERT_TYPE "ALERT_DEGRADED_RECOVERY")}}
74+
"color": "#2eb886",
75+
{{/if}}
76+
{{#if (eq ALERT_TYPE "ALERT_DEGRADED")}}
77+
"color": "#daa038",
78+
{{/if}}
79+
"blocks": [
80+
{
81+
"type": "header",
82+
"text": {
83+
"type": "plain_text",
84+
"text": "Check Result Details",
85+
"emoji": true
86+
}
87+
},
88+
{
89+
"type": "section",
90+
"fields": [
91+
{
92+
"type": "mrkdwn",
93+
"text": "*Check:*\n<https://app.checklyhq.com/checks/{{CHECK_ID}}|{{CHECK_NAME}}>"
94+
},
95+
{{#if GROUP_NAME}}
96+
{
97+
"type": "mrkdwn",
98+
"text": "*Group:*\n{{GROUP_NAME}}"
99+
},
100+
{{/if}}
101+
{
102+
"type": "mrkdwn",
103+
"text": "*Type:*\n{{CHECK_TYPE}}"
104+
},
105+
{
106+
"type": "mrkdwn",
107+
"text": "*Started at:*\n{{STARTED_AT}}"
108+
},
109+
{
110+
"type": "mrkdwn",
111+
"text": "*Run Location:*\n`{{RUN_LOCATION}}`"
112+
},
113+
{
114+
"type": "mrkdwn",
115+
"text": "*Response Time:*\n{{RESPONSE_TIME}}ms"
116+
}
117+
{{#if API_CHECK_RESPONSE_STATUS_CODE}},
118+
{
119+
"type": "mrkdwn",
120+
"text": "*Status Code:*\n{{API_CHECK_RESPONSE_STATUS_CODE}} {{API_CHECK_RESPONSE_STATUS_TEXT}}"
121+
}
122+
{{/if}}
123+
]
124+
},
125+
{{#if CHECK_ERROR_MESSAGE}}
126+
{
127+
"type": "section",
128+
"text": {
129+
"type": "mrkdwn",
130+
"text": "*❌ Error Message:*\n```{{CHECK_ERROR_MESSAGE}}```"
131+
}
132+
},
133+
{{/if}}
134+
135+
{{#if (eq ALERT_TYPE "ALERT_RECOVERY")}}
136+
{
137+
"type": "section",
138+
"text": {
139+
"type": "mrkdwn",
140+
"text": "✅ *This check has recovered and is now passing successfully.*"
141+
}
142+
},
143+
{{/if}}
144+
145+
{{#if (eq ALERT_TYPE "ALERT_DEGRADED_RECOVERY")}}
146+
{
147+
"type": "section",
148+
"text": {
149+
"type": "mrkdwn",
150+
"text": "🟡 *This check has recovered from a degraded state.*"
151+
}
152+
},
153+
{{/if}}
154+
155+
{{#if (eq ALERT_TYPE "ALERT_DEGRADED")}}
156+
{
157+
"type": "section",
158+
"text": {
159+
"type": "mrkdwn",
160+
"text": "⚠️ *This check is running but performance is degraded.*"
161+
}
162+
},
163+
{{/if}}
164+
165+
{
166+
"type": "section",
167+
"text": {
168+
"type": "mrkdwn",
169+
"text": "🔎 *View full result:*\n<{{RESULT_LINK}}|Click here to view details in Checkly>"
170+
}
171+
},
172+
{
173+
"type": "actions",
174+
"elements": [
175+
{
176+
"type": "button",
177+
"text": {
178+
"type": "plain_text",
179+
"text": "Runbook",
180+
"emoji": true
181+
},
182+
{{#if (eq CHECK_NAME "Check A")}}
183+
"url": "https://example.com/check-a",
184+
{{else if (eq CHECK_NAME "Check B")}}
185+
"url": "https://example.com/check-b",
186+
{{else}}
187+
"url": "https://example.com/default",
188+
{{/if}}
189+
"action_id": "open_link_button"
190+
},
191+
{
192+
"type": "button",
193+
"text": {
194+
"type": "plain_text",
195+
"text": "OTel Provider",
196+
"emoji": true
197+
},
198+
"url": "https://example.com",
199+
"action_id": "open_link_button_needs_to_be_unique"
200+
}
201+
]
202+
},
203+
{
204+
"type": "context",
205+
"elements": [
206+
{
207+
"type": "plain_text",
208+
"text": "Tags: {{TAGS}} | UUID: {{CHECK_RESULT_ID}}",
209+
"emoji": false
210+
}
211+
]
212+
}
213+
]
214+
}
215+
]
216+
}
217+
```
218+
219+
>[!NOTE]
220+
> Be sure to update or remove the placeholder button links to Runbooks, OTel provider and anything else that is not needed for your use case.
221+
222+
>[!NOTE]
223+
> Be sure each check mapped in the runbook logic has a corresponding URL. If a match isn’t found, fallback to a default documentation page.
224+
225+
### Testing the Webhook Limitations
226+
* You cannot use the Test Webhook button in Checkly for this template, as Slack requires valid payload structure and the test payload lacks real check data.
227+
* To test, trigger a real alert by adjusting a check so it fails, degrades, and recovers.
228+
229+
### Examples of Alert Transitions
230+
231+
![A customized slack message showing a failed alert](/docs/images/alerting/slack-custom-failed.png)
232+
233+
![A customized slack message showing a degraded alert](/docs/images/alerting/slack-custom-degraded.png)
234+
235+
![A customized slack message showing a recovered alert](/docs/images/alerting/slack-custom-recovered.png)
236+
237+
![A customized slack message showing a recovered alert from degraded state](/docs/images/alerting/slack-custom-recovered-degraded.png)

0 commit comments

Comments
 (0)