Skip to content

Commit 93be091

Browse files
thebiglabaskythebiglabasky
authored
Document webhook Handlebars helpers (#450)
1 parent ab2628f commit 93be091

2 files changed

Lines changed: 54 additions & 20 deletions

File tree

‎integrations/alerts/webhooks.mdx‎

Lines changed: 53 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: "Webhook Integrations"
3-
description: "Create custom webhook integrations to send Checkly alerts to any API endpoin"
3+
description: "Create custom webhook integrations to send Checkly alerts to any API endpoint"
44
sidebarTitle: "Webhooks"
55
canonical: 'https://www.checklyhq.com/docs/integrations/alerts/webhooks/'
66
---
@@ -88,21 +88,60 @@ When [automatic Rocky AI analysis](/resolve/ai-root-cause-analysis/overview#auto
8888

8989
### Handlebars Helpers
9090

91-
| Helper | Description |
92-
| -------------------- | ------------------------------------------------------------------------- |
93-
| `{{$UUID}}` | Generates a random UUID/v4 (e.g., `9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d`) |
94-
| `{{$RANDOM_NUMBER}}` | Generates a random decimal number between 0 and 1000 (e.g., `345`) |
95-
| `{{moment}}` | Generates dates/times using **moment.js** with formatting: |
91+
Webhook templates support [Handlebars built-in helpers](https://handlebarsjs.com/guide/builtin-helpers.html), such as `if`, `unless`, and `each`, as well as these Checkly helpers:
9692

97-
- `{{moment "YYYY-MM-DD"}}` → `2020-08-26`
98-
- `{{moment "2 days ago" "YYYY-MM-DD"}}` → `2020-08-24`
99-
- `{{moment "last week" "X"}}` → `1597924480`
93+
| Helper | Example | Description |
94+
| --- | --- | --- |
95+
| `$UUID` | `{{$UUID}}` | Generates a random UUID v4, such as `9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d`. |
96+
| `$RANDOM_NUMBER` | `{{$RANDOM_NUMBER}}` | Generates a random integer from 0 through 10,000. |
97+
| `tagValue` | `{{tagValue TAGS "team" "UNKNOWN"}}` | Returns the value from the first matching `team:value` or `team=value` tag. Returns the optional final argument when no tag matches. |
98+
| `startsWith` | `{{startsWith value "prefix:"}}` | Returns whether a string starts with the supplied prefix. |
99+
| `replace` | `{{replace value "old" "new"}}` | Replaces the first matching string. |
100+
| `split` | `{{split "a,b,c" "," 1}}` | Splits a string and returns the item at the supplied zero-based index. |
101+
| `year` | `{{year}}` or `{{year 2}}` | Returns the current year with four or two digits. |
102+
| `date`, `moment` | `{{date "YYYY-MM-DD"}}` | Formats the current date. The two helper names are aliases. |
100103

101-
<Note>
102-
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/).
103-
</Note>
104+
#### Get a value from a tag
105+
106+
Use `tagValue` when your tags store key-value metadata. Given these tags:
107+
108+
```text
109+
team:payments
110+
environment=production
111+
```
104112

105-
You can also use conditional helpers like `{{#eq}}` statements. Here is an example:
113+
This template:
114+
115+
```handlebars
116+
{{tagValue TAGS "team" "UNKNOWN"}}
117+
```
118+
119+
renders `payments`. Both `:` and `=` separators are supported. If neither `team:...` nor `team=...` exists, the template renders the fallback `UNKNOWN`. If multiple tags match, Checkly returns the first one.
120+
121+
<Tip>
122+
Send a test message from the webhook editor to inspect the rendered request before saving your alert channel.
123+
</Tip>
124+
125+
#### Format dates and times
126+
127+
The `date` and `moment` helpers support [Day.js-compatible format tokens](https://day.js.org/docs/en/display/format). You can format the current time, an absolute date, or relative phrases such as `yesterday`, `2 days ago`, and `last week`.
128+
129+
- `{{date "YYYY-MM-DD"}}` formats the current date, for example as `2026-07-24`.
130+
- `{{date "2026-07-24" "MMMM DD, YYYY"}}` renders `July 24, 2026`.
131+
- `{{moment "2 days ago" "YYYY-MM-DD"}}` formats the date from two days ago.
132+
- `{{moment "last week" "X"}}` formats last week as a Unix timestamp.
133+
134+
#### Compare values
135+
136+
Use comparison helpers as blocks or subexpressions where applicable. Available helpers include:
137+
138+
- Equality and ordering: `eq`, `is`, `isnt`, `gt`, `gte`, `lt`, `lte`, and `compare`.
139+
- Boolean logic: `and`, `or`, `not`, `neither`, `isTruthy`, and `isFalsey`.
140+
- Value checks: `contains`, `has`, and `default`.
141+
- Numeric conditions: `ifEven`, `ifOdd`, and `ifNth`.
142+
- Inverse comparisons: `unlessEq`, `unlessGt`, `unlessGteq`, `unlessLt`, and `unlessLteq`.
143+
144+
For example:
106145

107146
```json
108147
{
@@ -127,8 +166,6 @@ Two clear benefits here:
127166
- You only need to create one webhook to inform a 3rd party system.
128167
- You can translate Checkly terms to your 3rd party tool's term for the same concept, i.e. the "up status" of a check.
129168

130-
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.
131-
132169
## Webhook Secrets
133170

134171
You can validate each webhook we deliver to your endpoint(s). Using the optional webhook secret, you can:
@@ -447,4 +484,4 @@ An example body could look as follows:
447484

448485
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).
449486

450-
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/).
487+
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/).

‎platform/snippets/handlebars-snippets.mdx‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,4 @@ Notice three things:
9999

100100
## Using Handlebars helpers
101101

102-
We've extended the [Handlebars](https://handlebarsjs.com/) templating system with some handy helpers to make our webhooks
103-
even more powerful.
104-
105-
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.
102+
Webhook templates support additional Checkly helpers for extracting tag values, formatting dates, comparing values, and transforming strings. See [Handlebars helpers for webhooks](/integrations/alerts/webhooks#handlebars-helpers) for the supported helpers and examples.

0 commit comments

Comments
 (0)