Repository navigation
feat: expose group-by values to webhook bodies as {{var.<column>}} - #3384
Conversation
Generic and incident.io webhook bodies can reference the breaching group's
values by column, e.g. "{{var.customer_id}} has an elevated error rate".
Resolve notifications now carry the group's values too, so {{attributes.x}}
in alert names and messages no longer renders empty on resolve.
🦋 Changeset detectedLatest commit: 4b9f050 The changes in this PR will be included in the next version bump. This PR includes changesets to release 4 packages
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 |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
🟡 Tier 3 — StandardIntroduces new logic, modifies core functionality, or touches areas with non-trivial risk. Why this tier:
Additional context: touches background tasks or the delivery pipeline lightly (18 lines, under the 30-line bar for Tier 4), spans packages but only 21 prod lines — under the 100-line cross-layer bar Review process: Full human review — logic, architecture, edge cases. Stats
|
Duplicate code analysisNo new duplicate code introduced by this PR. jscpd compared this branch against |
| @@ -21,6 +21,7 @@ a HyperDX alert without parsing the human-readable message body. | |||
| | `{{thresholdMax}}` | number | Upper bound of a `between`/`outside` condition. Always unset for every other comparator, even if the alert was once a range, so guard it (see below). | | |||
| | `{{value}}` | number | The value that triggered or resolved the alert. | | |||
There was a problem hiding this comment.
🔵 minor — Bracket syntax in the docs doesn't cover map-attribute group-bys
parseAlertData (index.ts:940) uses ClickHouse's result column name as the key. For the common OTel group-by ResourceAttributes['service.name'], the key is that whole expression, not service.name. It also contains a ], so the documented {{var.[service.name]}} renders empty and a plain [...] segment can't reach the key. Fix: say that the key is the literal group-by expression unless it is aliased, and document {{lookup var "ResourceAttributes['service.name']"}} for keys like this.
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
| thresholdMax: 'Upper bound of a between/outside range (number)', | ||
| value: 'Value that triggered or resolved the alert (number)', | ||
| groupKey: 'The breaching group, if grouped', | ||
| var: 'Group-by values by column, e.g. {{var.customer_id}}', |
There was a problem hiding this comment.
🔵 minor — Form lists {{var}} as a variable, but using it as shown renders [object Object]
getWebhookTemplateVariables displays each entry as {{name}}, so the list shows {{var}} next to scalar variables. That object is useless on its own: a body containing {{var}} renders [object Object]. Fix: display this entry as {{var.<column>}}, for example by special-casing object-valued names in getWebhookTemplateVariables, so the label shows the form users actually need.
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
PR Review
4 finding(s): 🔴 0 critical · 🟠 0 major · 🔵 4 minor 4 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. |
[Medium impact] The PR appears safe to merge; no actionable issues were found. SummaryGrouped alerts now expose individual group values through
|
Deep Review✅ No critical (P0/P1) issues found. The change reuses the established 🟡 P2 — recommended
🔵 P3 nitpicks (2)
Reviewers (returned at synthesis): security, previous-comments, agent-native, plus orchestrator diff analysis (correctness/adversarial/testing lenses). Additional persona reviewers (api-contract, reliability, maintainability, project-standards, kieran-typescript, learnings) were dispatched but had not returned when output was required; findings above reflect completed results and direct code reading. Note: Testing gaps:
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 |
E2E Test Results✅ All tests passed • 445 passed • 1 skipped • 1430s
Tests ran across 4 shards in parallel. |
| thresholdMax: 10, | ||
| value: 7, | ||
| groupKey: 'test-group', | ||
| groupValues: { group: 'test-group' }, |
There was a problem hiding this comment.
🔵 minor — Send test fills only var.group, so a body using a real group-by column can't be checked
The PR says the test lets you check a body before an alert fires. But the test payload is hardcoded to { group: 'test-group' }, so {{var.customer_id}} or {{var.ServiceName}} (the PR's own repro) still renders as an empty string. Fix: walk the body's Handlebars AST for var.<name> paths, the way findUndeliverableConstruct in packages/api/src/utils/webhookBodyTemplate.ts already walks it, and fill each one with a sample value.
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
| thresholdMax: 'Upper bound of a between/outside range (number)', | ||
| value: 'Value that triggered or resolved the alert (number)', | ||
| groupKey: 'The breaching group, if grouped', | ||
| var: 'Group-by values by column, e.g. {{var.customer_id}}', |
There was a problem hiding this comment.
🔵 minor — Variable list shows {{var}} as a token to use, but on its own it renders [object Object]
getWebhookTemplateVariables wraps every name as {{name}}, so the form lists {{var}}. Pasting that into a body puts [object Object] in the payload. Every other entry in the list works as a complete token. Fix: render this entry as {{var.<column>}}, either with a display-name override for var or by building the name from the descriptions map.
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
| thresholdMax: message.thresholdMax, | ||
| value: message.value, | ||
| }) satisfies Record<WebhookTemplateVariable, string | number | undefined>; | ||
| }) satisfies Record< |
There was a problem hiding this comment.
🔵 minor — Widened satisfies lets any template variable be an object, which weakens the type check
Adding Record<string, string> to the shared value union means title, body and the rest could become objects without a type error. Fix: give var its own type, e.g. satisfies Record<Exclude<WebhookTemplateVariable, 'var'>, string | number | undefined> & { var: Record<string, string> }.
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
| : undefined, | ||
| value, | ||
| groupKey: group ?? '', | ||
| groupValues: groupValues ?? {}, |
There was a problem hiding this comment.
🔵 minor — No test checks that real alert notifications pass groupValues through to the webhook message
The new int test only checks the Slack title, which comes from the separate attributes path. generic.test.ts calls buildWebhookTemplateVariables directly. So if groupValues: attributes in fireChannelEvent or groupValues ?? {} here were dropped, every test would still pass. Fix: add a checkAlerts int test with a Generic webhook whose body uses {{var.ServiceName}}, and assert the rendered request body on both fire and resolve.
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
| string, | ||
| { value: number; attributes: Record<string, string>; startTime: Date } | ||
| >(); | ||
| // ponytail: a group that vanished from the data resolves without its values. |
There was a problem hiding this comment.
🔵 minor — Stray ponytail: prefix in a code comment
ponytail: doesn't match any comment-tag convention in this file and looks like a leftover personal marker. Drop the prefix and keep the explanation of why a vanished group resolves without its values.
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
The group-by test cast the mock and its argument, adding two no-unsafe-type-assertion warnings that put @hyperdx/api over its lint warning limit. Use jest.mocked like the rest of the file.
| teamId, | ||
| teamWebhooksById, | ||
| sampleLines, | ||
| groupValues: attributes, |
There was a problem hiding this comment.
🔵 minor — No test checks that real alert group values reach a webhook body as {{var.*}}
If you deleted groupValues: attributes from fireChannelEvent, or groupValues: groupValues ?? {} from template.ts:758, every test would still pass. generic.test.ts calls buildWebhookTemplateVariables directly, webhooks.int.test.ts only covers the hardcoded test-send payload, and the new checkAlerts test only checks the Slack title, which comes from view.attributes. Add a checkAlerts int test with a generic webhook whose body is {{var.ServiceName}}, and assert the posted body on both the firing and the resolve notification.
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
| thresholdMax: 'Upper bound of a between/outside range (number)', | ||
| value: 'Value that triggered or resolved the alert (number)', | ||
| groupKey: 'The breaching group, if grouped', | ||
| var: 'Group-by values by column, e.g. {{var.customer_id}}', |
There was a problem hiding this comment.
🔵 minor — The variable list shows {{var}}, and using it as shown sends [object Object]
getWebhookTemplateVariables displays every entry as {{name}}. Every other entry in the list works if copied as-is, but {{var}} is an object, so Handlebars renders it as the string [object Object] in the request body. Show this entry as {{var.<column>}}, or skip the {{name}} wrapping for var, so the copyable token actually works.
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
| thresholdMax: message.thresholdMax, | ||
| value: message.value, | ||
| }) satisfies Record<WebhookTemplateVariable, string | number | undefined>; | ||
| }) satisfies Record< |
There was a problem hiding this comment.
🔵 minor — Widening the satisfies value type lets any variable be an object
Adding Record<string, string> to the shared value union means a mistake like title: someObject now type-checks and renders [object Object]. Keep the old union for the scalar variables and type only var as the object, e.g. satisfies Record<Exclude<WebhookTemplateVariable, 'var'>, string | number | undefined> & { var: Record<string, string> }.
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
| teamId, | ||
| teamWebhooksById, | ||
| sampleLines, | ||
| groupValues: attributes, |
There was a problem hiding this comment.
🔵 minor — No test covers the new groupValues path from a real alert to the webhook body
The new unit test in generic.test.ts calls buildWebhookTemplateVariables directly. The new checkAlerts int test only checks the Slack title, which comes from view.attributes, not groupValues. So deleting groupValues: attributes here, or groupValues: groupValues ?? {} in template.ts:758, would still pass every test. Add an int test where a grouped alert uses a Generic webhook with body {{var.ServiceName}}, and assert the rendered body on both fire and resolve.
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
| thresholdMax: 'Upper bound of a between/outside range (number)', | ||
| value: 'Value that triggered or resolved the alert (number)', | ||
| groupKey: 'The breaching group, if grouped', | ||
| var: 'Group-by values by column, e.g. {{var.customer_id}}', |
There was a problem hiding this comment.
🔵 minor — The variable list shows {{var}}, which renders [object Object] if pasted as written
getWebhookTemplateVariables displays every entry as {{${name}}}. Every other row can be pasted as-is, but {{var}} in a body renders the object as [object Object]. Display this entry as {{var.<column>}}, either with a per-variable display-name override or by special-casing object variables in getWebhookTemplateVariables.
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
| { value: number; attributes: Record<string, string>; startTime: Date } | ||
| >(); | ||
| // ponytail: a group that vanished from the data resolves without its values. | ||
| const groupAttributes = new Map<string, Record<string, string>>(); |
There was a problem hiding this comment.
🔵 minor — groupAttributes repeats attributes already stored in bucketEvaluations and latestAlertContext
groupKey is built deterministically from extraFields, so the new groupAttributes map always holds the same attributes as bucketEvaluations[groupKey].attributes and latestAlertContext[groupKey].attributes. That leaves three copies. Use groupAttributes.get(groupKey) in the fire path too and remove attributes from the other two maps. Also replace the ponytail: prefix on the comment with a plain explanation.
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
| thresholdMax: message.thresholdMax, | ||
| value: message.value, | ||
| }) satisfies Record<WebhookTemplateVariable, string | number | undefined>; | ||
| }) satisfies Record< |
There was a problem hiding this comment.
🔵 minor — Widened satisfies type lets every template variable be an object
Adding Record<string, string> to the shared value union means a scalar variable such as title or groupKey could become an object and still compile. That silently loosens the guarantee the comment above claims. Keep the scalar union for the other keys and type var alone as Record<string, string>, e.g. Record<Exclude<WebhookTemplateVariable, 'var'>, string | number | undefined> & { var: Record<string, string> }.
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
Summary
Webhook bodies for grouped alerts can now name the group they're about:
{"summary": "{{var.customer_id}} has an elevated error rate"}renders the breaching group's value. Before, the only group variable was{{groupKey}}, a joined string likecustomer_id:acme, region:euthat a receiver had to parse.{{var.<column>}}works in Generic and incident.io bodies, keyed by group-by column or SQL alias. Values are JSON-escaped like the other string variables.{{attributes.x}}in alert names and messages used to render empty on resolve, so a firing title of "Errors for service-b" resolved as "Errors for ".{{var.group}}so a body can be checked before an alert fires.groupKey, and parsing values back out of that string isn't safe.{{var.[service.name]}}. The docs say so.Screenshots or video
The webhook form's variable list gains a
{{var}}row. Screenshots not captured; I'll add them before review.How to reproduce
Starting point:
yarn dev(alerts and webhooks need the API).On this branch:
{"text": "{{var.ServiceName}} has errors"}pointed at a request bin.ServiceName, using that webhook."checkout has errors". Onmainthe same body renders" has errors".How to test on Vercel preview
N/A: needs the API.