Repository navigation
docs(webhooks): double brackets insert raw values in the URL, headers and query parameters [RED-1427] - #847
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
hlenke
left a comment
There was a problem hiding this comment.
Needs changes · Hold the merge until checkly/monorepo#6921 is merged and deployed (it is still open today), and scope the new URL note to your own variables and secrets, because event variables are URL-encoded in the URL.
The edits match what checkly/monorepo#6921 implements at its current head (3d7406be): in the URL, header values and query parameter values, {{ }} no longer HTML-escapes, and the payload body still does. One nuance is missing from the page, see the inline comment on integrations/alerts/webhooks.mdx line 32.
Merge gate. checkly/monorepo#6921 is OPEN and not merged. On monorepo main (60c1d20321) the webhook channel still renders headers and query parameters with the default HTML-escaping template, so these pages would be wrong if merged today. The PR description already says this; I'm repeating it so the verdict is clear.
CI, conflicts, overlap. All checks pass. GitHub reports MERGEABLE / CLEAN, and main has not touched either file since the merge base. Draft #830 also edits platform/variables.mdx, but only line 19 (agent → runner), so the two don't conflict. pr_impact.py finds no removed anchors or broken links.
Inline comments: 1 Important.
What I checked
- Read the full diff from merge base
f5b606a9and both touched files in the PR version, including the event-variable table, the tags section, and the Slack example that still uses triple braces in the body (still correct, since the body keeps HTML escaping). git grepacross all.mdxfor triple brackets,HTML-escap,=: no other page gives the old advice for webhook URLs, headers or query parameters.detect/synthetic-monitoring/api-checks/configuration.mdxdescribes HTML escaping for API checks, which #6921 does not change.snippets/alert-channel-secrets-callout.mdx: says nothing about escaping, so it stays consistent.- checkly/monorepo#6921 at
3d7406be(read through the API): the webhook channel renders the URL, header values and query parameter values without HTML escaping and keeps it in the body. It percent-encodes the event variables before they go into the URL, replaces line breaks in event variables with spaces in headers, and keepsCHECK_ERROR_MESSAGEHTML-escaped. Monorepomainat60c1d20321still HTML-escapes everywhere. gh pr checks 847,gh pr view 847(mergeable),git logof the touched files since the merge base,gh pr listfor overlap,pr_impact.py.- No end-to-end test. The local app runs monorepo
main, which does not contain #6921, so a local webhook run would show the old behavior. I checked the claims against the PR's source instead.
|
|
||
| <Note> | ||
| 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. |
There was a problem hiding this comment.
Important · With checkly/monorepo#6921, {{NAME}} inserts your variables and secrets as stored in the URL, headers and query parameters. The event variables in the table below behave differently: they are URL-encoded before they go into the URL, so {{CHECK_NAME}} with a space arrives as %20, and line breaks in them become spaces in a header. As written, "{{NAME}} inserts the value as stored" reads as if it covers {{CHECK_NAME}} too, and the table intro says event variables work "in both URL and payload".
| 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 your variables and secrets as stored, so a variable or secret can hold a whole URL with a query string. Event variables such as `{{CHECK_NAME}}` are URL-encoded in the URL, and line breaks in them become spaces in headers. 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. |
hlenke
left a comment
There was a problem hiding this comment.
Needs changes · One fix left: the new CHECK_ERROR_MESSAGE row implies triple brackets give the raw error message in the payload, but it stays HTML-escaped there with both forms.
This review covers the one commit since 987429e3 (798a0739, no merge of main in between).
- Scope of the URL note (previous Important): the note now says
{{NAME}}inserts the value of a variable or secret as stored, and the new paragraph and list under the event variables say how event variables are encoded outside the payload. Fixed. - The new encoding list matches the webhook channel on monorepo
main(05df6b0ac7), which now contains checkly/monorepo#6921: event variables reach the URL, headers and query parameters only when the channel has a payload template; in the URL they are percent-encoded (a/b & cgivesa%2Fb%20%26%20c); in headers control characters become spaces and non-ASCII characters are percent-encoded as UTF-8 (CafégivesCaf%C3%A9); query parameter values go in raw and are percent-encoded when the query string is built. - The Trello example now sends
nameanddescin a JSON payload, which fixes the empty card name the URL-only version produced, since event variables need a payload template.
Merge gate. checkly/monorepo#6921 was merged on 2026-11-17. The PR description asks to merge only after it is deployed to production; I could not verify the deployment from here.
CI. preview-checks fails with 1 failed, 4 passed, 5 total and does not name the check; the same failure shows on other open PRs today (for example #859), and #860, which filters tracker errors on previews, is still open. Not caused by this PR. All other checks pass.
Conflicts and overlap. MERGEABLE; main has not changed either file since the merge base f5b606a9. Draft #830 edits a different line of platform/variables.mdx.
Inline: 1 important.
What I checked
git diff 987429e3 798a0739(integrations/alerts/webhooks.mdxonly) and the touched sections at the PR head.- checkly/monorepo#6921:
MERGEDat 2026-11-17T17:56:37Z (gh pr view). - Monorepo
mainat05df6b0ac7, the webhook alert channel underapps/backend/api/src/common/services/alert-notification-service/channels/webhook/: the request is rendered with event variables only when a template is set; the URL variant percent-encodes event variables; the header variant replaces control characters with spaces and percent-encodes non-ASCII characters; query parameter values are percent-encoded when the URL's query string is built. The payload'sCHECK_ERROR_MESSAGEis HTML-escaped once when the event is tokenized and passed as a Handlebars safe string, and the URL, headers and query parameters get the unescaped message. The unit tests in the same folder assert the payload value equals the HTML-escaped error. git greponmainfor triple-bracket uses ofCHECK_ERROR_MESSAGE: none.gh pr checks 847, failed run 44497726489 log;gh pr view 847(MERGEABLE,UNSTABLEfrom the failing check);git log <base>..origin/mainon both files (no changes).- Not verified: that Trello's
POST /1/cardsreadsnameanddescfrom a JSON body; I did not call Trello. No end-to-end test: the local app does not deliver webhooks to an external receiver I could inspect, so I checked the claims against source.
| | `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. | |
There was a problem hiding this comment.
| | `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. | |
Important. "HTML-escaped in the payload with double brackets, like any other variable" reads as if {{{CHECK_ERROR_MESSAGE}}} gives the raw message, as triple brackets do for every other variable (the note at line 32 says so). It doesn't: the webhook channel HTML-escapes the error message once when it builds the payload variables and passes it as a Handlebars safe string, so {{ }} and {{{ }}} both output the escaped text (monorepo main, apps/backend/api/src/common/services/alert-notification-service/channels/webhook/index.ts; the unit tests in that folder assert the escaped value). Only the URL, headers and query parameters get the unescaped message.
… 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 <noreply@anthropic.com>
…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
…th triple brackets too Claude-Session: https://claude.ai/code/session_012Z3Budq8jjLK9SALNX37GM
e88fb35 to
3405f4c
Compare
Important
Merge after checkly/monorepo#6921 is deployed to production. Until then, these pages would describe behavior that isn't live yet.
What
checkly/monorepo#6921 stops HTML-escaping
{{NAME}}in a webhook alert channel's URL, header values and query parameter values. The payload body keeps HTML escaping. Event variables (CHECK_NAME,ALERT_TITLE,CHECK_ERROR_MESSAGE, …) are encoded there instead, so that they cannot change the request. This PR updates the docs to match:{{NAME}}inserts the raw value of a variable or secret in the URL, headers and query parameters, so a variable or secret can hold a whole URL with a query string. Double brackets still escape in the body, and triple brackets still give the raw value there. Triple brackets keep working everywhere, so existing setups that use them don't need to change.{{NAME}}URL to{{{NAME}}}. The lock icon's{{NAME}}now works for a URL with a query string. This also matters because the integration forms (Microsoft Teams, Slack webhook, Discord, …) accept only a literal URL or{{NAME}}, not{{{NAME}}}.Café→Caf%C3%A9); query values are percent-encoded as before.CHECK_ERROR_MESSAGE: HTML-escaped in the payload with double and triple brackets, not in the URL, headers or query parameters.nameanddescin a JSON payload.Unchanged on purpose: the body examples that use triple brackets (tags, Slack text).
🤖 Generated with Claude Code
https://claude.ai/code/session_012Z3Budq8jjLK9SALNX37GM