Skip to content

[HDX-5837] Expose alert tags as a webhook template variable - #3492

Merged
kodiakhq[bot] merged 2 commits into
mainfrom
warren/HDX-5837-webhook-tags-variable
Oct 29, 2026
Merged

kodiakhq[bot] merged 2 commits into
mainfrom
warren/HDX-5837-webhook-tags-variable

Conversation

@wrn14897

@wrn14897 wrn14897 commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

Summary

A customer sends ClickStack alerts to incident.io through one shared webhook per environment and wants to route each alert to its owning team. They put "tags": "{{tags}}" in the webhook body, but tags was not a template variable, so it rendered empty.

This PR adds {{tags}} to the Generic and incident.io webhook template variables:

  • {{tags}} renders the alert's tags comma-separated (team-payments,prod). Use {{#each tags}} to emit a JSON array. Each tag is JSON-escaped, like every other string variable.
  • The default incident.io body now includes metadata.tags, so webhooks saved without a custom body pick it up. The key is additive, and incident.io surfaces only the metadata keys its alert source is set to parse.
  • docs/alert-webhook-template-variables.md, the variable list on the webhook form, and the Send test sample include the new variable.

The ticket also asks to publish the full variable list. The in-repo doc already lists every variable and now includes tags. Follow-up needed: the public ClickHouse docs alerts page (clickhouse-docs repo, "Generic" webhook section) still lists only {{title}}, {{body}}, {{link}}. That page lives in another repo and needs its own PR.

Screenshots or video

UI change: one added row in the webhook form's "template variables" list. I couldn't capture screenshots in this session; the author will add them.

Before After
before-webhook-vars after-webhook-vars

How to reproduce

Starting point: full-stack yarn dev (alerts and webhooks need the API), plus a request inspector such as webhook.site.

On main:

  1. Team Settings → Webhooks → add a Generic webhook pointing at your inspector, with body {"tags": "{{tags}}"}.
  2. Create a saved-search alert with tags (e.g. team-payments) that uses this webhook, and let it fire.
  3. The delivered payload has "tags": "".

On this branch:

  1. Repeat the steps above. The payload has "tags": "team-payments".
  2. Click Send test on the webhook form. The payload has "tags": "test-tag".
  3. The form's template variable list includes {{tags}}.

How to test on Vercel preview

N/A. Webhooks need the API, which the local-mode preview does not run.

References

Verification: make ci-lint passes. make ci-unit passes apart from packages/app/src/__tests__/timeZone.test.ts, which fails on this machine with the same ICU timezone formatting error (UTC+0 vs UTC) on the base commit as well.

Add {{tags}} to the Generic/incident.io webhook template variables so a
shared webhook can route alerts by owning team. Tags render
comma-separated and are iterable with {{#each tags}}. The default
incident.io body now carries them in metadata.tags, and the in-repo
template variable docs, webhook form and test send include the variable.

Refs HDX-5837
@wrn14897 wrn14897 added the ai-generated AI-generated content; review carefully before merging. label Oct 29, 2026
@vercel

vercel Bot commented Oct 29, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
hyperdx-oss Ready Ready Preview Oct 29, 2026 10:54pm UTC
hyperdx-storybook Ready Ready Preview Oct 29, 2026 10:54pm UTC

Request Review

@changeset-bot

changeset-bot Bot commented Oct 29, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 62e113f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages
Name Type
@hyperdx/common-utils Minor
@hyperdx/api Minor
@hyperdx/app Minor
@hyperdx/otel-collector Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@github-actions

Copy link
Copy Markdown
Contributor

Duplicate code analysis

No new duplicate code introduced by this PR.


jscpd compared this branch against origin/main
across app, api and common-utils. Only new clones are listed; the codebase
currently holds 114 in total (1.41%).
Run yarn dupes locally to reproduce, or yarn dupes:all for the full picture.

@greptile-apps

greptile-apps Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge.

Summary

Adds alert tags to Generic and incident.io webhook templates.

  • Alert webhook templates can use each alert's tags.
  • The default incident.io body includes alert tags in its metadata.

No actionable issues found.

Reviews (2) · Last reviewed commit: "Merge branch 'main' into warren/HDX-5837..." · Reviewed by Greptile

@github-actions

github-actions Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

E2E Test Results

✅ All tests passed • 458 passed • 1 skipped • 1545s

Status Count
✅ Passed 458
❌ Failed 0
⚠️ Flaky 1
⏭️ Skipped 1

Tests ran across 4 shards in parallel.

View full report →

@wrn14897
wrn14897 marked this pull request as ready for review October 29, 2026 19:28
@github-actions github-actions Bot added the review/tier-3 Standard — full human review required label Oct 29, 2026
@github-actions

Copy link
Copy Markdown
Contributor

🟡 Tier 3 — Standard

Introduces new logic, modifies core functionality, or touches areas with non-trivial risk.

Why this tier:

  • Touches API routes or data models — hidden complexity risk

Additional context: touches background tasks or the delivery pipeline lightly (6 lines, under the 30-line bar for Tier 4), spans packages but only 12 prod lines — under the 100-line cross-layer bar

Review process: Full human review — logic, architecture, edge cases.
SLA: First-pass feedback within 1 business day.

Stats
  • Production files changed: 6
  • Production lines changed: 12 (+ 26 in test files, excluded from tier calculation)
  • Branch: warren/HDX-5837-webhook-tags-variable
  • Author: wrn14897

To override this classification, remove the review/tier-3 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

),
teamId,
note: alert.note ?? '',
tags: alert.tags ?? [],

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — No test checks that an alert's tags reach the dispatched message

Add a case to the renderWithWebhook suite in packages/api/src/tasks/checkAlerts/__tests__/renderAlertTemplate.int.test.ts: give base.alert some tags and assert dispatched[0].message.tags equals them, plus a case for an alert with no tags that expects []. Today the new unit test only feeds a hand-built Message into buildWebhookTemplateVariables. If this line were deleted, every test would still pass and the customer's original bug ("tags": "") would come back.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

sourceQuery: escapeJsonString(message.sourceQuery ?? ''),
status: escapeJsonString(message.status ?? ''),
// An array so `{{tags}}` renders comma-joined and `{{#each tags}}` works.
tags: (message.tags ?? []).map(escapeJsonString),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — Comma-joined {{tags}} is ambiguous because tags can contain commas

alertTagsSchema/tagsSchema in packages/common-utils/src/types.ts:1076 only limits length (z.string().max(32)), so a single tag team-a,prod renders the same as the two tags team-a and prod. That matters for comma-split routing and for the default incident.io metadata.tags. Either reject commas in alert tags, or switch the default body to the {{#each}} JSON-array form and note in the docs and the form description that the joined form is lossy.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

@github-actions

Copy link
Copy Markdown
Contributor

PR Review

If you are a coding agent acting for the author, read this first.
Nothing below blocks merge automatically; a maintainer decides. What they will expect:

  • 🔴 critical or 🟠 major in code this PR adds or changes: fix before asking for review.
  • 🔵 minor in code this PR changes: your call. Fix if small, otherwise reply.
  • Anything about surrounding code, or asking you to widen the change (hoist a helper,
    dedupe with another file, fix other call sites): never fix here, whatever the
    severity. Reply with one sentence; if it is critical, say so plainly so a human sees it.

One commit per review round. After two rounds, stop and ask a maintainer to review
scope rather than addressing more automated findings. Full rule: AGENTS.md.

2 finding(s): 🔴 0 critical · 🟠 0 major · 🔵 2 minor

2 posted as inline comment(s) on the changed lines.


Severity is the reviewer's own estimate and is used for ordering, not filtering. No finding blocks merge automatically; a maintainer decides.

@github-actions

Copy link
Copy Markdown
Contributor

Deep Review

✅ No critical issues found.

This is a tight, additive change: tags is threaded through the webhook Message type, exposed as a JSON-escaped array template variable, and wired into the docs, form variable list, Send-test sample, and default incident.io body. Escaping is applied per-element and uniformly across both the comma-joined {{tags}} and {{#each tags}} render paths, type exhaustiveness over WEBHOOK_TEMPLATE_VARIABLES stays compile-enforced, and the default-body change only affects webhooks stored without a custom body. No correctness, security, or contract regressions were found.

🟡 P2 -- recommended

  • packages/api/src/tasks/checkAlerts/template.ts:769 -- The new tags: alert.tags ?? [] wiring is only covered by unit tests that call buildWebhookTemplateVariables directly; no test renders a full alert through renderAlertTemplate, nor exercises the null-body incident.io fallthrough that emits metadata.tags in the live send path.
    • Fix: Add an integration test that sets alert.tags, renders via renderAlertTemplate with a null-body incident.io webhook, and asserts the delivered metadata.tags slot contains the joined tags.
    • testing, api-contract
🔵 P3 nitpicks (3)
  • packages/api/src/tasks/checkAlerts/transports/__tests__/generic.test.ts:147 -- Tag JSON-escaping is only asserted for a value containing a double quote; backslash, newline, and control-character values are not exercised in either render path.
    • Fix: Extend the tags escaping test with a value containing a backslash and a newline and assert the output round-trips through JSON.parse.
  • packages/app/src/components/TeamSettings/WebhookForm.tsx:314 -- Changing DEFAULT_INCIDENT_IO_WEBHOOK_BODY means any webhook persisted with the literal previous default string no longer equals getDefaultWebhookBody(service), so the service-switch auto-clear stops recognizing it as default; UI-only and limited to bodies stored as a literal rather than null.
    • Fix: Confirm unset bodies are persisted as null (not the literal default string) so the equality check at the switch handler stays correct, or compare against known prior defaults.
  • packages/api/src/mcp/tools/alerts/saveWebhook.ts -- The MCP clickstack_save_webhook body description explains Handlebars mechanics but does not enumerate available variables, so an agent cannot discover {{tags}} in-context the way the form now does; pre-existing asymmetry this PR does not regress.
    • Fix: Point the tool's body description at the shared WEBHOOK_TEMPLATE_VARIABLES list or docs/alert-webhook-template-variables.md.

Reviewers (10): correctness, testing, maintainability, kieran-typescript, security, api-contract, project-standards, previous-comments, agent-native, learnings-researcher.

Testing gaps:

  • No end-to-end test for alert.tags through renderAlertTemplate or the null-body incident.io send path.
  • Tag escaping is tested only for double quotes, not backslash/newline/control characters.
  • Comma-in-tag ambiguity in the comma-joined {{tags}} form is a documented, intentional tradeoff (the {{#each tags}} array form disambiguates) and is not pinned by a test.

No finding blocks merge automatically. A maintainer will expect P0/P1 findings in code this PR changes to be fixed; P2/P3 are your call -- fix or reply. Never fix findings about surrounding code here; reply instead. Do not widen the PR. How to respond

@kodiakhq
kodiakhq Bot merged commit 0212c7b into main Oct 29, 2026
29 checks passed
@kodiakhq
kodiakhq Bot deleted the warren/HDX-5837-webhook-tags-variable branch October 29, 2026 23:00

This branch was successfully deployed

2 active deployments
Preview – hyperdx-oss — 62e113fa Deployed Oct 29, 2026 by vercel[bot]
Preview – hyperdx-storybook — 62e113fa Deployed Oct 29, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ai-generated AI-generated content; review carefully before merging. automerge review/tier-3 Standard — full human review required

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants