You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Webhooks allow you to POST custom payloads to any endpoint in your own infrastructure or a third party provider. In a nutshell, you can:
13
14
14
15
- Create a **custom URL** by adding in authentication tokens or other secrets.
15
16
- Create a **custom payload body** using any environment variables and specific instance variables per event. Note: that means that if you are attaching the webhook to a Group, you will be able to access Group-level variables, too.
16
17
-**Debug and test the webhook** in the editor by sending test messages.
The example above shows a webhook configured to create a Jira ticket on each event. Notice the following:
23
22
24
23
- We use the variable `JIRA_INSTANCE_URL` in the URL. We previously stored this variable in the [environment variables section](https://app.checklyhq.com/environment-variables). Alerting configurations only support the use of environment variables, secrets are not supported.
@@ -27,47 +26,51 @@ The example above shows a webhook configured to create a Jira ticket on each eve
27
26
In both cases we use the familiar Handlebars templating braces, i.e. `{{ }}` to insert the variable.
28
27
29
28
<Note>
30
-
To avoid encoding, you can access your environment variables with triple brackets, i.e. `{{{USER_API_KEY}}}`
29
+
To avoid encoding, you can access your environment variables with triple brackets, i.e. `{{{USER_API_KEY}}}`
31
30
</Note>
32
31
33
32
You can use the following event-related variables in both URL and payload.
|`ALERT_TITLE`| Human readable title, e.g. 'Check "My API check" has failed' |
38
-
|`ALERT_TYPE`| Type of alert, e.g. "ALERT_FAILURE", "ALERT_RECOVERY", "ALERT_DEGRADED", "ALERT_DEGRADED_RECOVERY". See [alert states](/communicate/alerts/overview#alert-states) for all options. |
39
-
|`API_CHECK_RESPONSE_STATUS_CODE`| The response status code, e.g. 200. Only populated for API checks. |
40
-
|`API_CHECK_RESPONSE_STATUS_TEXT`| The response status text, e.g. "OK". Only populated for API checks. |
41
-
|`CHECK_ERROR_MESSAGE`| The check error message |
42
-
|`CHECK_ID`| The UUID of the check |
43
-
|`CHECK_NAME`| Full name of the check |
44
-
|`CHECK_RESULT_ID`| The UUID of the result that triggered this message |
45
-
|`CHECK_TYPE`| The check type, e.g. API, BROWSER . |
46
-
|`GROUP_NAME`| The name of the group, if the check belongs to one. |
47
-
|`REGION`| AWS region code where check ran, e.g. "us-east-1" |
48
-
|`RESPONSE_TIME`| The reported response time for this result |
49
-
|`RESULT_LINK`| The full link to the check result |
50
-
|`RUN_LOCATION`| The location where the check ran, i.e. "N. California" |
51
-
|`SSL_CHECK_DOMAIN`| The domain of the SSL certificate. For ALERT_SSL only. |
52
-
|`SSL_DAYS_REMAINING`| How many days remain on the SSL certificate. For ALERT_SSL only.|
53
-
|`STARTED_AT`| The ISO timestamp from when this check run started |
54
-
|`TAGS`| An array of tags assigned to the check. Have a look at our Opsgenie example below on how to render this to a JSON array. |
|`AI_ANALYSIS_CLASSIFICATION`| Classification of the failure / error. Available when AI automation is enabled. |
37
+
|`AI_ANALYSIS_CODE_FIX`| A code fix to resolve the analyzed problem. Available when AI automation is enabled. |
38
+
|`AI_ANALYSIS_LINK`| Direct link to full AI analysis. Available when AI automation is enabled. |
39
+
|`AI_ANALYSIS_ROOT_CAUSE`| Description of possible root cause. Available when AI automation is enabled. |
40
+
|`AI_ANALYSIS_USER_IMPACT`| Description of the user impact. Available when AI automation is enabled. |
41
+
|`ALERT_TITLE`| Human readable title, e.g. 'Check "My API check" has failed' |
42
+
|`ALERT_TYPE`| Type of alert, e.g. "ALERT_FAILURE", "ALERT_RECOVERY", "ALERT_DEGRADED", "ALERT_DEGRADED_RECOVERY". See [alert states](/communicate/alerts/overview#alert-states) for all options. |
43
+
|`API_CHECK_RESPONSE_STATUS_CODE`| The response status code, e.g. 200. Only populated for API checks. |
44
+
|`API_CHECK_RESPONSE_STATUS_TEXT`| The response status text, e.g. "OK". Only populated for API checks. |
45
+
|`CHECK_ERROR_MESSAGE`| The check error message |
46
+
|`CHECK_ID`| The UUID of the check |
47
+
|`CHECK_NAME`| Full name of the check |
48
+
|`CHECK_RESULT_ID`| The UUID of the result that triggered this message |
49
+
|`CHECK_TYPE`| The check type, e.g. API, BROWSER . |
50
+
|`GROUP_NAME`| The name of the group, if the check belongs to one. |
51
+
|`REGION`| AWS region code where check ran, e.g. "us-east-1" |
52
+
|`RESPONSE_TIME`| The reported response time for this result |
53
+
|`RESULT_LINK`| The full link to the check result |
54
+
|`RUN_LOCATION`| The location where the check ran, i.e. "N. California" |
55
+
|`SSL_CHECK_DOMAIN`| The domain of the SSL certificate. For ALERT_SSL only. |
56
+
|`SSL_DAYS_REMAINING`| How many days remain on the SSL certificate. For ALERT_SSL only. |
57
+
|`STARTED_AT`| The ISO timestamp from when this check run started |
58
+
|`TAGS`| An array of tags assigned to the check. Have a look at our Opsgenie example below on how to render this to a JSON array. |
55
59
56
60
### Handlebars Helpers
57
61
58
-
| Helper | Description |
59
-
|--------|-------------|
60
-
|`{{$UUID}}`| Generates a random UUID/v4 (e.g., `9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d`) |
61
-
|`{{$RANDOM_NUMBER}}`| Generates a random decimal number between 0 and 1000 (e.g., `345`) |
62
-
| `{{moment}}` | Generates dates/times using **moment.js** with formatting:
|`{{$UUID}}`| Generates a random UUID/v4 (e.g., `9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d`) |
65
+
|`{{$RANDOM_NUMBER}}`| Generates a random decimal number between 0 and 1000 (e.g., `345`) |
66
+
|`{{moment}}`| Generates dates/times using **moment.js** with formatting:|
63
67
64
68
-`{{moment "YYYY-MM-DD"}}` → `2020-08-26`
65
69
-`{{moment "2 days ago" "YYYY-MM-DD"}}` → `2020-08-24`
66
70
-`{{moment "last week" "X"}}` → `1597924480`
67
71
68
72
<Note>
69
-
You can find the [full list of helpers in the README.md file](https://github.com/checkly/handlebars) of the underlying library we are using.
70
-
For a full overview of date formatting option, check the [moment.js docs](https://momentjs.com/docs/#/displaying/format/).
73
+
You can find the [full list of helpers in the README.md file](https://github.com/checkly/handlebars) of the underlying library we are using. For a full overview of date formatting option, check the [moment.js docs](https://momentjs.com/docs/#/displaying/format/).
71
74
</Note>
72
75
73
76
You can also use conditional helpers like `{{#eq}}` statements. Here is an example:
@@ -80,7 +83,7 @@ You can also use conditional helpers like `{{#eq}}` statements. Here is an examp
80
83
81
84
The above webhook body uses the `{{#eq}}` helper to execute the logic
82
85
83
-
*If the ALERT_TYPE variable equals 'ALERT_FAILURE', print 'DOWN', if it equals 'ALERT_RECOVERY' print 'UP'*
86
+
_If the ALERT_TYPE variable equals 'ALERT_FAILURE', print 'DOWN', if it equals 'ALERT_RECOVERY' print 'UP'_
84
87
85
88
So in the case of a failure event, the body would render to:
86
89
@@ -91,6 +94,7 @@ So in the case of a failure event, the body would render to:
91
94
```
92
95
93
96
Two clear benefits here:
97
+
94
98
- You only need to create one webhook to inform a 3rd party system.
95
99
- You can translate Checkly terms to your 3rd party tool's term for the same concept, i.e. the "up status" of a check.
96
100
@@ -103,11 +107,9 @@ You can validate each webhook we deliver to your endpoint(s). Using the optional
103
107
1. Check if the webhook was sent by Checkly.
104
108
2. Check if the payload was not altered in any way during transmission.
105
109
106
-
When you create a webhook secret, we proceed to use that secret token to cryptographically sign the webhook payload using
107
-
the SHA256 hash algorithm. We add the resulting hash to the HTTP header `x-checkly-signature` on each webhook.
110
+
When you create a webhook secret, we proceed to use that secret token to cryptographically sign the webhook payload using the SHA256 hash algorithm. We add the resulting hash to the HTTP header `x-checkly-signature` on each webhook.
108
111
109
-
On the receiving end, you can then use the value of the `x-checkly-signature` header to assert the validity and authenticity
110
-
of the webhook and its payload.
112
+
On the receiving end, you can then use the value of the `x-checkly-signature` header to assert the validity and authenticity of the webhook and its payload.
111
113
112
114
Have a look at the code examples below on how to use the header and your favourite web framework.
app.listen(4242, () =>console.log('Running on port 4242'))
144
146
```
145
147
148
+
146
149
```ruby Ruby
147
150
# We store the webhook secret in an environment variable called CHECKLY_WEBHOOK_SECRET
148
151
require'sinatra'
@@ -164,6 +167,7 @@ post '/webhook' do
164
167
end
165
168
```
166
169
170
+
167
171
```python Python
168
172
# This example assumes you use Django
169
173
import hmac
@@ -190,20 +194,19 @@ def webhook(request):
190
194
191
195
## Webhook Retries
192
196
193
-
Checkly will retry your webhook up to **5 times** if we get an HTTP response higher than 399, e.g. a 404 or 503. Each retry
194
-
is backed off 20 seconds for a total retry period of `5 * 20 = 100 seconds`.
197
+
Checkly will retry your webhook up to **5 times** if we get an HTTP response higher than 399, e.g. a 404 or 503. Each retry is backed off 20 seconds for a total retry period of `5 * 20 = 100 seconds`.
195
198
196
-
This means that for checks on a 1 minute schedule, there is a potential overlap between a failure alert and recovery alert. For this
197
-
reason every webhook we send has a timestamp in the `x-checkly-timestamp` header. You can use this timestamp on the receiving
198
-
end to ignore any webhooks that come in "late".
199
+
This means that for checks on a 1 minute schedule, there is a potential overlap between a failure alert and recovery alert. For this reason every webhook we send has a timestamp in the `x-checkly-timestamp` header. You can use this timestamp on the receiving end to ignore any webhooks that come in "late".
199
200
200
201
## Webhook Examples
201
202
202
203
The following examples give an idea how to integrate Checkly with 3rd party alerting and issue tracking systems.
203
204
204
205
### OpsGenie
205
206
206
-
You can create an <ahref="https://docs.opsgenie.com/docs/alert-api"target="_blank">OpsGenie</a> alert by POST-ing the following body
207
+
You can create an <ahref="https://docs.opsgenie.com/docs/alert-api"target="_blank">OpsGenie</a>
208
+
209
+
alert by POST-ing the following body
207
210
208
211
```json
209
212
{
@@ -296,7 +299,6 @@ Send a message using [Pushover](https://pushover.net/) by posting this body:
296
299
}
297
300
```
298
301
299
-
300
302
### Trello
301
303
302
304
You can create a [Trello](https://trello.com) card using just the URL and no payload:
@@ -316,15 +318,15 @@ You can send your SSL alerts using webhooks. Using the following body:
316
318
}
317
319
```
318
320
319
-
Will yield the following output, where we customize the `ALERT_TITLE` to include the domain and the days remaining till your
320
-
certificate expires.
321
+
Will yield the following output, where we customize the `ALERT_TITLE` to include the domain and the days remaining till your certificate expires.
321
322
322
323
```json
323
324
{
324
325
"message": "The SSL certificate for api.checklyhq.com will expire in 14 days",
You can configure a webhook to POST to a JavaScript snippet running in a [Twilio Function](https://www.twilio.com/docs/runtime/functions). This code receives the Checkly webhook JSON, then triggers a Twilio "Flow execution":
@@ -416,4 +418,4 @@ An example body could look as follows:
416
418
417
419
For full details on creating issues via the Jira API, see [Atlassian's documentation for this endpoint](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-post).
418
420
419
-
You can also use version 2 of the Jira API (i.e. `{{JIRA_INSTANCE_URL}}/rest/api/2/issue`). The only difference is that version 2 does not support [Atlassian Document Format (ADF)](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/).
421
+
You can also use version 2 of the Jira API (i.e. `{{JIRA_INSTANCE_URL}}/rest/api/2/issue`). The only difference is that version 2 does not support [Atlassian Document Format (ADF)](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/).
![mintlify[bot]](https://avatars.githubusercontent.com/in/222410?v=4&size=40){kind=avatar}
0 commit comments