From e6a1b7c6ad301ce07d9e253ee0595e6e28eadee5 Mon Sep 17 00:00:00 2001 From: Hannes Lenke Date: Mon, 16 Nov 2026 20:11:59 -0500 Subject: [PATCH 1/3] docs(webhooks): double brackets insert raw values in the URL, headers and query parameters [RED-1427] Merge after checkly/monorepo#6921 is deployed: from then on `{{NAME}}` is no longer HTML-escaped in a webhook's URL, header values and query parameter values, so the lock icon's `{{NAME}}` works for a whole URL with a query string. The payload body keeps HTML escaping; triple brackets keep working. Co-Authored-By: Claude Opus 5.5 --- integrations/alerts/webhooks.mdx | 4 ++-- platform/variables.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/integrations/alerts/webhooks.mdx b/integrations/alerts/webhooks.mdx index 0e1c9e1d..2924b51e 100644 --- a/integrations/alerts/webhooks.mdx +++ b/integrations/alerts/webhooks.mdx @@ -29,14 +29,14 @@ The example above shows a webhook configured to create a Jira ticket on each eve In both cases we use the familiar Handlebars templating braces, i.e. `{{ }}` to insert the variable. - To avoid encoding, you can access your environment variables with triple brackets, i.e. `{{{USER_API_KEY}}}`. Double brackets HTML-escape the value everywhere you use them, including the URL, headers and query parameters: `&` arrives as `&` and `=` as `=`. Use triple brackets for a variable or secret that holds a whole URL, or any value that contains `&` or `=`. + In the URL, header values and query parameter values, `{{NAME}}` inserts the value as stored, so a variable or secret can hold a whole URL with a query string. In the payload body, double brackets HTML-escape the value: `&` arrives as `&` and `=` as `=`. To insert the raw value in the body, use triple brackets, i.e. `{{{USER_API_KEY}}}`. Triple brackets work in the URL, headers and query parameters too. A JSON payload template stays valid JSON when an inserted value contains a double quote or a line break: the value is escaped in the body we send. With `{{CHECK_NAME}}` a double quote arrives as `"`, with `{{{CHECK_NAME}}}` as `\"`; a line break arrives as `\n` in both cases. -When you promote a value with the lock icon, the field gets a `{{NAME}}` reference. If you promoted a whole URL with a query string, change the reference to `{{{NAME}}}`, or the escaped `=` and `&` break the URL. +When you promote a value with the lock icon, the field gets a `{{NAME}}` reference. This also works for a whole URL with a query string. You can use the following event-related variables in both URL and payload. diff --git a/platform/variables.mdx b/platform/variables.mdx index b4a10622..591893b1 100644 --- a/platform/variables.mdx +++ b/platform/variables.mdx @@ -91,7 +91,7 @@ How variables are accessed depends on where you're accessing them from: * In [webhook alert channels](/integrations/alerts/webhooks#using-variables), also use the Handlebar/Moustache format, i.e. `{{VARIABLE_NAME}}` - Handlebar (double brackets) variables are HTML-escaped: `&`, `<`, `>`, `"`, `'`, `` ` `` and `=` are replaced with HTML entities, for example `&` becomes `&`. To insert the raw value, access your environment variables with triple brackets, i.e. `{{{VARIABLE_NAME}}}`. + Handlebar (double brackets) variables are HTML-escaped: `&`, `<`, `>`, `"`, `'`, `` ` `` and `=` are replaced with HTML entities, for example `&` becomes `&`. To insert the raw value, access your environment variables with triple brackets, i.e. `{{{VARIABLE_NAME}}}`. The URL, header values and query parameter values of a webhook alert channel are the exception: there, double brackets insert the raw value too. ## Playwright Check Suite Variables From a11d7f8a031e692c1edafa1c78e7879990e42e4f Mon Sep 17 00:00:00 2001 From: Harald Wartig Date: Thu, 19 Nov 2026 10:34:42 +0100 Subject: [PATCH 2/3] docs(webhooks): describe how event variables are encoded outside the payload [RED-1427] checkly/monorepo#6921 encodes event variables (CHECK_NAME, ALERT_TITLE, ...) in the URL and headers, fills them there only with a payload template, and no longer HTML-escapes CHECK_ERROR_MESSAGE outside the payload. - Using Variables: raw "as stored" applies to variables and secrets; list the encoding of event variables per location and the template condition. - CHECK_ERROR_MESSAGE: HTML-escaped only in the payload. - Trello: the URL-only example sent an empty card name; use a payload. Claude-Session: https://claude.ai/code/session_012Z3Budq8jjLK9SALNX37GM --- integrations/alerts/webhooks.mdx | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/integrations/alerts/webhooks.mdx b/integrations/alerts/webhooks.mdx index 2924b51e..b302a687 100644 --- a/integrations/alerts/webhooks.mdx +++ b/integrations/alerts/webhooks.mdx @@ -29,7 +29,7 @@ The example above shows a webhook configured to create a Jira ticket on each eve In both cases we use the familiar Handlebars templating braces, i.e. `{{ }}` to insert the variable. - In the URL, header values and query parameter values, `{{NAME}}` inserts the value as stored, so a variable or secret can hold a whole URL with a query string. In the payload body, double brackets HTML-escape the value: `&` arrives as `&` and `=` as `=`. To insert the raw value in the body, use triple brackets, i.e. `{{{USER_API_KEY}}}`. Triple brackets work in the URL, headers and query parameters too. + In the URL, header values and query parameter values, `{{NAME}}` inserts the value of a variable or secret as stored, so a variable or secret can hold a whole URL with a query string. In the payload body, double brackets HTML-escape the value: `&` arrives as `&` and `=` as `=`. To insert the raw value in the body, use triple brackets, i.e. `{{{USER_API_KEY}}}`. Triple brackets work in the URL, headers and query parameters too. A JSON payload template stays valid JSON when an inserted value contains a double quote or a line break: the value is escaped in the body we send. With `{{CHECK_NAME}}` a double quote arrives as `"`, with `{{{CHECK_NAME}}}` as `\"`; a line break arrives as `\n` in both cases. @@ -38,7 +38,11 @@ A JSON payload template stays valid JSON when an inserted value contains a doubl When you promote a value with the lock icon, the field gets a `{{NAME}}` reference. This also works for a whole URL with a query string. -You can use the following event-related variables in both URL and payload. +You can use the following event-related variables in the payload, and in the URL, header values and query parameter values. Outside the payload, they are filled in only when the webhook has a payload template, and they are encoded so that they cannot change the request: + +- In the URL, the value is percent-encoded, e.g. a check named `a/b & c` arrives as `a%2Fb%20%26%20c`. +- In header values, line breaks and other control characters become spaces, and non-ASCII characters are percent-encoded as UTF-8, e.g. `Café` arrives as `Caf%C3%A9`. +- In query parameter values, the value is percent-encoded like any other query parameter value. | Variable | Description | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -51,7 +55,7 @@ You can use the following event-related variables in both URL and payload. | `ALERT_TYPE` | Type of alert, e.g. "ALERT_FAILURE", "ALERT_RECOVERY", "ALERT_DEGRADED", "ALERT_DEGRADED_RECOVERY". See [failures, recoveries and reminders](#failures-recoveries-and-reminders) for which state change sends which type. | | `API_CHECK_RESPONSE_STATUS_CODE` | The response status code, e.g. 200. Populated for API checks and URL monitors. | | `API_CHECK_RESPONSE_STATUS_TEXT` | The response status text, e.g. "OK". Populated for API checks and URL monitors. | -| `CHECK_ERROR_MESSAGE` | The check error message, HTML-escaped. See [which variables are filled per check type](#which-variables-are-filled-per-check-type) for when it's empty. | +| `CHECK_ERROR_MESSAGE` | The check error message. HTML-escaped in the payload with double brackets, like any other variable. See [which variables are filled per check type](#which-variables-are-filled-per-check-type) for when it's empty. | | `CHECK_ID` | The UUID of the check | | `CHECK_DESCRIPTION` | The description of the check, if set | | `CHECK_NAME` | Full name of the check | @@ -496,12 +500,23 @@ Compared to the Checkly Slack app: ### Trello -You can create a [Trello](https://trello.com) card using just the URL and no payload: +You can create a [Trello](https://trello.com) card with a `POST` to this URL: ``` -https://api.trello.com/1/cards?idList=5b28c04aed47522097be8bc4&key={{TRELLO_KEY}}&token={{TRELLO_TOKEN}}&name={{CHECK_NAME}} +https://api.trello.com/1/cards?idList=5b28c04aed47522097be8bc4&key={{TRELLO_KEY}}&token={{TRELLO_TOKEN}} +``` + +and this payload: + +```json +{ + "name": "{{{ALERT_TITLE}}}", + "desc": "{{{RESULT_LINK}}}" +} ``` +Event variables such as `ALERT_TITLE` are filled in only when the webhook has a payload template, so put them in the payload, not in the URL alone. + ### SSL alert You can send your SSL alerts using webhooks. Using the following body: From 3405f4c1be2c6cd4efef58d592cf626ccd8271e6 Mon Sep 17 00:00:00 2001 From: Harald Wartig Date: Thu, 19 Nov 2026 15:42:56 +0100 Subject: [PATCH 3/3] docs(webhooks): CHECK_ERROR_MESSAGE is HTML-escaped in the payload with triple brackets too Claude-Session: https://claude.ai/code/session_012Z3Budq8jjLK9SALNX37GM --- integrations/alerts/webhooks.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/integrations/alerts/webhooks.mdx b/integrations/alerts/webhooks.mdx index b302a687..fc43dd29 100644 --- a/integrations/alerts/webhooks.mdx +++ b/integrations/alerts/webhooks.mdx @@ -55,7 +55,7 @@ You can use the following event-related variables in the payload, and in the URL | `ALERT_TYPE` | Type of alert, e.g. "ALERT_FAILURE", "ALERT_RECOVERY", "ALERT_DEGRADED", "ALERT_DEGRADED_RECOVERY". See [failures, recoveries and reminders](#failures-recoveries-and-reminders) for which state change sends which type. | | `API_CHECK_RESPONSE_STATUS_CODE` | The response status code, e.g. 200. Populated for API checks and URL monitors. | | `API_CHECK_RESPONSE_STATUS_TEXT` | The response status text, e.g. "OK". Populated for API checks and URL monitors. | -| `CHECK_ERROR_MESSAGE` | The check error message. HTML-escaped in the payload with double brackets, like any other variable. See [which variables are filled per check type](#which-variables-are-filled-per-check-type) for when it's empty. | +| `CHECK_ERROR_MESSAGE` | The check error message. In the payload it is always HTML-escaped, with double and triple brackets. In the URL, header values and query parameter values it is not. See [which variables are filled per check type](#which-variables-are-filled-per-check-type) for when it's empty. | | `CHECK_ID` | The UUID of the check | | `CHECK_DESCRIPTION` | The description of the check, if set | | `CHECK_NAME` | Full name of the check |