Repository navigation
docs(webhooks): which variables are filled, escaping, retries and dedup keys - #817
Conversation
…tries and dedup keys Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
… variables Captured real webhook payloads: Browser CHECK_ERROR_MESSAGE (first error, 300 chars, line breaks removed), a missed heartbeat ping (STATE FAILING), and check-level variables overriding account variables. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nnel Tested on a local stack with API checks: a check in a group renders the group's variables whether the webhook is subscribed on the check or through the group; a check outside the group renders them empty, even through a channel that is also attached to the group. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
hlenke
left a comment
There was a problem hiding this comment.
Needs changes · The variable, escaping, retry, and deduplication claims match the webhook code. Three Important items close gaps the new text opens: the Opsgenie example now contradicts the new triple-bracket advice, CHECK_ERROR_MESSAGE has a second source, and GROUP_NAME is empty for heartbeats.
CI is green, the PR is mergeable (CLEAN), and main hasn't touched webhooks.mdx since the merge base.
Overlap with #811. The description says there is no overlap with #811, but #811 also edits integrations/alerts/webhooks.mdx (it adds a Slack incoming webhook example between Pushover and Trello). The hunks don't touch each other and git merge-tree of the two heads is clean, so either can land first. #811's new example uses triple braces for the same reason this PR gives, so the two agree.
Section placement. The new subsections sit under Using Variables, next to the variable table; Render tags sits under the tagValue helper; and Failures, recoveries and reminders comes between Webhook Retries and Webhook Examples. All of these read in a sensible order.
Inline: 3 Important (one is on an unchanged line, so GitHub shows it below), 3 Wording.
What I checked
- Read the full diff from the merge base
e0e0277f, andintegrations/alerts/webhooks.mdxat the PR head. gh pr checks 817: all pass.gh pr view:MERGEABLE/CLEAN.git log <base>..origin/main -- integrations/alerts/webhooks.mdx: no commits.pr_impact.py: no broken anchors;webhooks.mdxis a hub (26 inbound pages), and no existing heading changes. The new in-page anchors match their headings.- Overlap:
gh pr list --json number,files, andgit merge-tree --write-treeof PRs 811 and 817 (clean). - Local app unavailable (BUSY: someone's own Tilt is on the ports), so I verified against source instead. Monorepo
origin/main@84921d2637:apps/backend/api/src/common/services/alert-notification-service/channels/webhook/index.ts:- The URL, headers, and query parameters go through the same Handlebars compile as the body, so double brackets HTML-escape there too.
- Valid JSON is sent as a parsed object; otherwise the rendered string is sent.
- The request timeout is 5 seconds.
- The signature is computed once and stored on the queued request.
- Variable tokens: heartbeats return only the common tokens plus
STATE. API and URL checks fillCHECK_ERROR_MESSAGEfrom the request error. Browser and Multistep checks use the first error, trimmed, cut to 300 characters, with line breaks removed.CHECK_ERROR_MESSAGEis always HTML-escaped. The run's schedule error, when present, takes precedence for every type.ALERT_TYPEmapping: degraded→failing isALERT_FAILURE, failing→degraded isALERT_DEGRADED.
apps/backend/api/daemons/alerting-daemon/src/WebhooksDaemon.ts: a failed request is re-queued with the same config (same body,x-checkly-timestamp,x-checkly-signature), up to 5 retries with exponential backoff.apps/backend/api/src/common/services/alert-notification-service/AlertNotificationService.ts: check environment variables override account variables on a key collision, for every check type.- a check degrades label:
apps/webapp/src/pages/alert-channel-builder/PageAlertChannelBuilderNotificationsEvents.vue.
- The
Content-Typefor a non-JSON body and forContent-Type: application/jsonon invalid JSON comes from axios's default request transform. That's consistent with the code path above and with the PR's captured requests; I didn't run it. - Could not verify from source: the heartbeat
STARTED_ATformat (a ping timestamp in that format exists inapps/backend/api/src/modules/heartbeats/HeartbeatsController.ts, but I didn't trace it into the alert), the TCP200/SUCCESSor500/ERRORvalues, and the degraded→passing case that yieldsALERT_RECOVERY. The PR's captured payloads cover all three.
Outside this PR's diff
integrations/alerts/webhooks.mdx:387: Important (unchanged line,integrations/alerts/webhooks.mdxline 387 at the PR head) The Opsgenie example still renders tags with"{{this}}", which line 193 of this PR now says turnsenv=prodintoenv=prod. Update it in this PR so the page doesn't contradict itself:
"tags": [{{#each TAGS}} "{{{this}}}" {{#unless @last}},{{/unless}} {{/each}}]| | `CHECK_ERROR_MESSAGE` | Request errors | Request errors | Empty | Empty | Empty | First error | | ||
| | `API_CHECK_RESPONSE_STATUS_CODE`, `API_CHECK_RESPONSE_STATUS_TEXT` | Response status | Response status | `200` / `SUCCESS` or `500` / `ERROR` | Empty | Empty | Empty | | ||
| | `RESPONSE_TIME`, `RUN_LOCATION`, `REGION` | Filled | Filled | Filled | Filled | Empty | Filled | | ||
| | `STATE` | Empty | Empty | Empty | Empty | Filled | Empty | |
There was a problem hiding this comment.
Important Consider a GROUP_NAME row. The heartbeat branch of the webhook token builder returns before GROUP_NAME (and the SSL variables) are set, so GROUP_NAME is empty for a heartbeat monitor even when it belongs to a group. For the other types it's the group name, or empty outside a group (tokenizeCheckResult in monorepo apps/backend/api/src/common/services/alert-notification-service/channels/webhook/index.ts). Readers who route alerts by group are the ones this table is for. I verified this from source only, since the local app wasn't available.
…UP_NAME Two columns instead of seven, a GROUP_NAME row (empty for heartbeat monitors), Multistep checks next to Browser checks, and triple braces for tags in the Opsgenie example. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
What changed and why
The webhooks page lists every variable but doesn't say which ones have a value for which check type, how double brackets escape values outside the body, how a failure relates to its recovery and reminders, or how to recognize a retried webhook. Those are the questions people building incident integrations on top of webhooks keep running into. This PR extends
integrations/alerts/webhooks.mdxonly:{{NAME}}HTML-escapes values in the URL, headers and query parameters too (&→&,=→=), and when to use triple brackets. A short line after the secrets callout covers a URL promoted with the lock icon.API_CHECK_RESPONSE_STATUS_*are filled for URL monitors too (the old text said API checks only). It also adds the missingSTATEvariable, pointsCHECK_ERROR_MESSAGEto the new availability table, notes thatTAGSincludes group tags, and gives the heartbeatSTARTED_ATformat.CHECK_ERROR_MESSAGEis empty, and the fact that there is no variable for the request URL or method. It now also has a Browser checks column, how the Browser check error message is cut, and a missed-ping heartbeat example (STATEFAILING).GROUP_NAME: empty for heartbeat monitors, even in a group (code only: the heartbeat branch oftokenizeCheckResultreturns beforeGROUP_NAMEis set).env=prodisn't sent asenv=prod.Content-Typewe send for valid JSON, for other text, and when you set the header yourself.tagValuehelper).ALERT_TYPEeach state change sends, what a reminder carries, and a deduplication key.No overlap with open PRs: #811 edits
slack.mdxand #812 editscommunicate/alerts/overview.mdx; this PR doesn't touch either.How each claim was verified
Tested end to end on a local Checkly stack built from the latest product code. Real check runs triggered real alerts, and the webhooks went to a local HTTP listener that logged every request's method, URL, headers and raw body. The channel template used every variable. Checks were driven between passing, failing and degraded by changing what the target returned.
{{NAME}}HTML-escapes in URL, headers, query params and body (&→&,=→=);{{{NAME}}}doesn't&and=referenced in URL, header, query param and body; raw requests captured{{NAME}}and works with{{{NAME}}}…/hook/x?a=1&b=2: request arrived at?a=(rest lost) with double, intact with triple{{NAME}}; a promoted URL with a query string then breaks{{WEBHOOK_URL}}, the account secret was created, and the next alert went to?token=with the rest droppedAPI_CHECK_RESPONSE_STATUS_CODE/_TEXTfilled for API checks and URL monitors; TCP200/SUCCESSor500/ERROR; empty for DNS and heartbeatCHECK_ERROR_MESSAGE: filled on request errors (refused connection) for API/URL, empty on assertion failures, empty for TCP, DNS, heartbeat; HTML-escapedRESPONSE_TIME,RUN_LOCATION,REGIONempty for heartbeats;STATEonly for heartbeats (e.g.LATE)STARTED_ATis UTCYYYY-MM-DD HH:mm:ssTAGSincludes the group's tags;{{#each}}with{{{this}}}gives a JSON array,{{{TAGS}}}a comma-separated string,{{this}}escapes=team:payments,env=prodapplication/json; other text asapplication/x-www-form-urlencoded; aContent-Type: text/plainheader sends plain text;Content-Type: application/jsonon invalid JSON sends one JSON stringx-checkly-timestampandx-checkly-signatureCHECK_ID;CHECK_RESULT_ID/STARTED_ATbelong to the triggering run (recovery = first passing run)ALERT_TYPEper state change, including degraded→failing =ALERT_FAILURE, failing→degraded =ALERT_DEGRADED, failing→degraded→passing =ALERT_RECOVERY, passing→degraded→passing =ALERT_DEGRADED_RECOVERYALERT_DEGRADEDALERT_TYPE,IS_REMINDERtrue,REMINDER_SEQUENCE1, 2…, result ID andSTARTED_ATof the latest failing runCHECK_RESULT_ID+ALERT_TYPE+REMINDER_SEQUENCEidentify one notificationCHECK_ERROR_MESSAGEis the first error, cut to 300 characters, then line breaks removed; status code/text empty;RESPONSE_TIME,RUN_LOCATION,REGIONfilled;STATEemptyGET /v1/alert-notifications). Two failure alerts: the 318-character multi-line error arrived as 290 characters, lines joined, cut before its last words; status fields"";RESPONSE_TIME5735,RUN_LOCATIONFrankfurt,REGIONeu-central-1(also on the recovery)ALERT_FAILURE,STATEFAILING,STARTED_ATlike2026-11-09 00:30:21ZZ_DOCS_VAR=account, the same key=checkon a Browser check and on a Playwright Check Suite. Both checks' alerts renderedcheck; the heartbeat (no check variables) renderedaccountWhat couldn't be tested, and what was left out
CHECK_ERROR_MESSAGE, although the code joins the failures with;. Reported as a possible product bug.🤖 Generated with Claude Code