From c0455e4645efba5d82e010f046f823b1c564427e Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Fri, 9 Oct 2026 15:33:59 -0600 Subject: [PATCH 1/2] fix(app): show webhook body template compile errors in the editor Compile the webhook body template as the user edits it (debounced) and show the Handlebars error, with its line and column, under the editor. A broken template, e.g. JSON-escaped quotes inside a helper call, previously gave no feedback until an alert failed to deliver. --- .../webhook-body-template-validation.md | 8 +++ docs/alert-webhook-template-variables.md | 10 +++- .../TeamSettings/WebhookBodyValidation.tsx | 27 +++++++++ .../components/TeamSettings/WebhookForm.tsx | 22 ++++++- .../__tests__/WebhookForm.test.tsx | 45 ++++++++++++++ .../src/core/__tests__/handlebarsEnv.test.ts | 50 ++++++++++++++++ .../common-utils/src/core/handlebarsEnv.ts | 58 +++++++++++++++++++ 7 files changed, 216 insertions(+), 4 deletions(-) create mode 100644 .changeset/webhook-body-template-validation.md create mode 100644 packages/app/src/components/TeamSettings/WebhookBodyValidation.tsx diff --git a/.changeset/webhook-body-template-validation.md b/.changeset/webhook-body-template-validation.md new file mode 100644 index 0000000000..e541864458 --- /dev/null +++ b/.changeset/webhook-body-template-validation.md @@ -0,0 +1,8 @@ +--- +'@hyperdx/common-utils': patch +'@hyperdx/app': patch +--- + +fix: the webhook form now compiles the body template as you edit it and shows +the Handlebars error with its line and column. A broken template used to give +no feedback until an alert failed to deliver. diff --git a/docs/alert-webhook-template-variables.md b/docs/alert-webhook-template-variables.md index 22c8d84ee3..05d1a37539 100644 --- a/docs/alert-webhook-template-variables.md +++ b/docs/alert-webhook-template-variables.md @@ -67,6 +67,12 @@ number that may be absent. Compare against `undefined` rather than using Keep a newline or space between `{{/unless}}` and a closing `}` — Handlebars reads `}}}` as a triple-stache and fails to compile the template. +The template is Handlebars, not JSON: it only has to be JSON once rendered. +Write string arguments inside `{{ … }}` with plain or single quotes — +`{{#if (eq state "ALERT")}}` or `{{#if (eq state 'ALERT')}}` — never JSON-escaped +as `\"ALERT\"`, which Handlebars cannot parse. The webhook form shows where a +body fails to compile. + The **Send test** button on the webhook form fills every variable with a sample value, so a template that uses them can be checked before an alert fires. The sample is a `between` alert, so `{{thresholdMax}}` is populated there — a test @@ -93,13 +99,13 @@ instead if every group of a grouped alert should collapse into one incident. Routing by severity and deduping on the alert rather than the firing: -```json +``` { "alert_id": "{{alertId}}", "dedup_key": "{{alertId}}-{{groupKey}}", "status": "{{status}}", "summary": "{{title}}", - "urgency": "{{#if (eq alertType \"dashboard_chart\")}}low{{else}}high{{/if}}", + "urgency": "{{#if (eq alertType 'dashboard_chart')}}low{{else}}high{{/if}}", "value": {{value}}, "threshold": {{threshold}}, "window": { "start": "{{startTimeISO}}", "end": "{{endTimeISO}}" }, diff --git a/packages/app/src/components/TeamSettings/WebhookBodyValidation.tsx b/packages/app/src/components/TeamSettings/WebhookBodyValidation.tsx new file mode 100644 index 0000000000..335d4048ce --- /dev/null +++ b/packages/app/src/components/TeamSettings/WebhookBodyValidation.tsx @@ -0,0 +1,27 @@ +import { WebhookTemplateError } from '@hyperdx/common-utils/dist/core/handlebarsEnv'; +import { Alert, Code } from '@mantine/core'; +import { IconAlertTriangle } from '@tabler/icons-react'; + +const errorTitle = ({ line, column }: WebhookTemplateError) => { + if (line == null) return 'Template error'; + return column == null + ? `Template error on line ${line}` + : `Template error on line ${line}, column ${column}`; +}; + +export function WebhookBodyValidationAlert({ + error, +}: { + error: WebhookTemplateError; +}) { + return ( + } + title={errorTitle(error)} + data-testid="webhook-body-error" + > + {error.message} + + ); +} diff --git a/packages/app/src/components/TeamSettings/WebhookForm.tsx b/packages/app/src/components/TeamSettings/WebhookForm.tsx index 3fbc1d5c80..727083a051 100644 --- a/packages/app/src/components/TeamSettings/WebhookForm.tsx +++ b/packages/app/src/components/TeamSettings/WebhookForm.tsx @@ -1,9 +1,10 @@ -import { useEffect } from 'react'; +import { useEffect, useMemo } from 'react'; import { HTTPError } from 'ky'; import { Controller, SubmitHandler, useForm, useWatch } from 'react-hook-form'; import { ZodIssue } from 'zod'; import { json, jsonParseLinter } from '@codemirror/lang-json'; import { linter } from '@codemirror/lint'; +import { getWebhookTemplateError } from '@hyperdx/common-utils/dist/core/handlebarsEnv'; import { getDefaultWebhookBody, WEBHOOK_TEMPLATE_VARIABLES, @@ -23,6 +24,7 @@ import { Text, TextInput, } from '@mantine/core'; +import { useDebouncedValue } from '@mantine/hooks'; import { notifications } from '@mantine/notifications'; import { IconInfoCircleFilled } from '@tabler/icons-react'; import ReactCodeMirror, { @@ -31,6 +33,7 @@ import ReactCodeMirror, { } from '@uiw/react-codemirror'; import api from '@/api'; +import { WebhookBodyValidationAlert } from '@/components/TeamSettings/WebhookBodyValidation'; import { useBrandDisplayName } from '@/theme/ThemeProvider'; import { isValidUrl } from '@/utils'; @@ -133,6 +136,19 @@ export function WebhookForm({ } }, [webhook, form]); + const service = useWatch({ control: form.control, name: 'service' }); + const bodyText = useWatch({ control: form.control, name: 'body' }); + // Debounced so the error doesn't flash while a {{ … }} is half-typed. + const [debouncedBody] = useDebouncedValue(bodyText, 300); + const bodyError = useMemo( + // Slack sends a fixed payload and never renders the body. + () => + service === WebhookService.Slack + ? null + : getWebhookTemplateError(debouncedBody), + [service, debouncedBody], + ); + const handleTestWebhook = async (values: WebhookForm) => { const { service, url, body, headers } = values; @@ -288,7 +304,6 @@ export function WebhookForm({ } }; - const service = useWatch({ control: form.control, name: 'service' }); // A body left at the old service's default would still be sent verbatim, and // each service's default is invalid to the others' receivers. A hand-edited // body is the user's, so it survives the switch. @@ -418,6 +433,9 @@ export function WebhookForm({ )} /> , + bodyError && ( + + ), } key="5" diff --git a/packages/app/src/components/TeamSettings/__tests__/WebhookForm.test.tsx b/packages/app/src/components/TeamSettings/__tests__/WebhookForm.test.tsx index 87c1ed806a..11032b47d0 100644 --- a/packages/app/src/components/TeamSettings/__tests__/WebhookForm.test.tsx +++ b/packages/app/src/components/TeamSettings/__tests__/WebhookForm.test.tsx @@ -132,4 +132,49 @@ describe('WebhookForm', () => { screen.queryByTestId('webhook-template-variables'), ).not.toBeInTheDocument(); }); + describe('body template validation', () => { + const ESCAPED_QUOTES_BODY = + '{"status": "{{#if (eq state \\"ALERT\\")}}firing{{else}}resolved{{/if}}"}'; + + async function fillIncidentIoWebhook( + user: ReturnType, + body: string, + ) { + await user.click(screen.getByRole('radio', { name: 'incident.io' })); + await user.type(screen.getByTestId('webhook-name-input'), 'oncall'); + await user.type( + screen.getByTestId('webhook-url-input'), + 'https://api.incident.io/v2/alert_events/http/abc?token=xyz', + ); + // incident.io has no headers editor, so the only editor is the body. + await user.click(screen.getByTestId('codemirror')); + await user.paste(body); + } + + it('shows a compile error inline', async () => { + const user = userEvent.setup(); + renderForm(); + await fillIncidentIoWebhook(user, ESCAPED_QUOTES_BODY); + + const error = await screen.findByTestId('webhook-body-error'); + expect(error).toHaveTextContent('Template error on line 1, column 29'); + expect(error).toHaveTextContent('Parse error on line 1'); + }); + + it('saves a template that is only valid JSON once rendered', async () => { + const user = userEvent.setup(); + const body = + '{"status": "{{#if (eq state "ALERT")}}firing{{else}}resolved{{/if}}"}'; + renderForm(); + await fillIncidentIoWebhook(user, body); + await user.click(screen.getByTestId('add-webhook-button')); + + expect(mockSaveWebhook).toHaveBeenCalledWith( + expect.objectContaining({ body }), + ); + expect( + screen.queryByTestId('webhook-body-error'), + ).not.toBeInTheDocument(); + }); + }); }); diff --git a/packages/common-utils/src/core/__tests__/handlebarsEnv.test.ts b/packages/common-utils/src/core/__tests__/handlebarsEnv.test.ts index c1bf2a4934..a798d38a22 100644 --- a/packages/common-utils/src/core/__tests__/handlebarsEnv.test.ts +++ b/packages/common-utils/src/core/__tests__/handlebarsEnv.test.ts @@ -2,9 +2,14 @@ import { clearTemplateCache, compileLenient, compileStrict, + getWebhookTemplateError, UnknownTemplateHelperError, validateTemplate, } from '@/core/handlebarsEnv'; +import { + DEFAULT_GENERIC_WEBHOOK_BODY, + DEFAULT_INCIDENT_IO_WEBHOOK_BODY, +} from '@/types'; describe.each([ ['compileStrict', compileStrict], @@ -128,3 +133,48 @@ describe('validateTemplate', () => { expect(() => validateTemplate('{{missing}}')).not.toThrow(); }); }); + +describe('getWebhookTemplateError', () => { + it('accepts a template that is invalid JSON before rendering', () => { + const body = + '{"status": "{{#if (eq state "ALERT")}}firing{{else}}resolved{{/if}}"}'; + expect(() => JSON.parse(body)).toThrow(); + expect(getWebhookTemplateError(body)).toBe(null); + }); + + it.each([DEFAULT_GENERIC_WEBHOOK_BODY, DEFAULT_INCIDENT_IO_WEBHOOK_BODY])( + 'accepts the default body %#', + body => { + expect(getWebhookTemplateError(body)).toBe(null); + }, + ); + + it('rejects JSON-escaped quotes inside a helper call', () => { + const body = + '{"status": "{{#if (eq state \\"ALERT\\")}}firing{{else}}resolved{{/if}}"}'; + expect(() => JSON.parse(body)).not.toThrow(); + expect(getWebhookTemplateError(body)).toEqual({ + message: expect.stringContaining('Parse error on line 1'), + line: 1, + column: 29, + }); + }); + + it('reports the line and column of a parse error on a later line', () => { + expect(getWebhookTemplateError('{\n "a": "{{title}"\n}')).toMatchObject({ + line: 2, + column: 16, + }); + }); + + it('reports the location of a mismatched block', () => { + expect(getWebhookTemplateError('{{#if x}}{{/each}}')).toMatchObject({ + message: expect.stringContaining("if doesn't match each"), + line: 1, + }); + }); + + it.each(['', ' \n', undefined])('accepts an empty body (%p)', body => { + expect(getWebhookTemplateError(body)).toBe(null); + }); +}); diff --git a/packages/common-utils/src/core/handlebarsEnv.ts b/packages/common-utils/src/core/handlebarsEnv.ts index 5bdd2c63fb..81076f3a35 100644 --- a/packages/common-utils/src/core/handlebarsEnv.ts +++ b/packages/common-utils/src/core/handlebarsEnv.ts @@ -134,3 +134,61 @@ export const clearTemplateCache = () => { strictCache.clear(); lenientCache.clear(); }; + +export type WebhookTemplateError = { + message: string; + line?: number; + column?: number; +}; + +const toFiniteNumber = (value: unknown): number | undefined => + typeof value === 'number' && Number.isFinite(value) ? value : undefined; + +// Reads a property off a value of unknown shape without a type assertion. +const read = (value: unknown, key: string): unknown => + value != null && typeof value === 'object' + ? Reflect.get(value, key) + : undefined; + +// Handlebars reports 0-based columns. +const toLocation = (line: unknown, column: unknown) => { + const col = toFiniteNumber(column); + return { + line: toFiniteNumber(line), + column: col == null ? undefined : col + 1, + }; +}; + +/** + * Compiles a webhook body template and returns the error, with its line and + * column where Handlebars knows them, or null when it compiles. Delivery + * renders with stock Handlebars plus an `eq` helper; helpers don't affect + * compilation, so stock Handlebars catches the same errors. An empty body + * compiles: it falls back to the default template. + */ +export function getWebhookTemplateError( + template: string | undefined, +): WebhookTemplateError | null { + if (!template?.trim()) return null; + try { + // compile() is lazy; precompile() parses and compiles up front. + Handlebars.precompile(template, { noEscape: true }); + return null; + } catch (e) { + const message = e instanceof Error ? e.message : String(e); + if (read(e, 'lineNumber') != null) { + return { + message, + ...toLocation(read(e, 'lineNumber'), read(e, 'column')), + }; + } + // Parse errors carry only the line, in the message. The lexer that just + // failed still holds the offending token's position. Parsing is + // synchronous, so nothing has run since. + const loc = read(read(read(Handlebars, 'Parser'), 'lexer'), 'yylloc'); + return { + message, + ...toLocation(read(loc, 'first_line'), read(loc, 'first_column')), + }; + } +} From e13fe6ae72c0aeb844fac4430c99fdc555534f52 Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Fri, 9 Oct 2026 15:43:02 -0600 Subject: [PATCH 2/2] test(app): wait out the webhook body debounce before asserting no error (greptile P2) --- .../__tests__/WebhookForm.test.tsx | 37 +++++++++++++++---- 1 file changed, 29 insertions(+), 8 deletions(-) diff --git a/packages/app/src/components/TeamSettings/__tests__/WebhookForm.test.tsx b/packages/app/src/components/TeamSettings/__tests__/WebhookForm.test.tsx index 11032b47d0..2d9a22eef0 100644 --- a/packages/app/src/components/TeamSettings/__tests__/WebhookForm.test.tsx +++ b/packages/app/src/components/TeamSettings/__tests__/WebhookForm.test.tsx @@ -5,7 +5,12 @@ import { } from '@hyperdx/common-utils/dist/types'; import { MantineProvider } from '@mantine/core'; import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; -import { render, screen } from '@testing-library/react'; +import { + act, + render, + screen, + waitForElementToBeRemoved, +} from '@testing-library/react'; import userEvent from '@testing-library/user-event'; import { @@ -133,6 +138,8 @@ describe('WebhookForm', () => { ).not.toBeInTheDocument(); }); describe('body template validation', () => { + const VALID_BODY = + '{"status": "{{#if (eq state "ALERT")}}firing{{else}}resolved{{/if}}"}'; const ESCAPED_QUOTES_BODY = '{"status": "{{#if (eq state \\"ALERT\\")}}firing{{else}}resolved{{/if}}"}'; @@ -161,20 +168,34 @@ describe('WebhookForm', () => { expect(error).toHaveTextContent('Parse error on line 1'); }); - it('saves a template that is only valid JSON once rendered', async () => { + it('clears the error once the template is fixed', async () => { const user = userEvent.setup(); - const body = - '{"status": "{{#if (eq state "ALERT")}}firing{{else}}resolved{{/if}}"}'; renderForm(); - await fillIncidentIoWebhook(user, body); - await user.click(screen.getByTestId('add-webhook-button')); + await fillIncidentIoWebhook(user, ESCAPED_QUOTES_BODY); + await screen.findByTestId('webhook-body-error'); - expect(mockSaveWebhook).toHaveBeenCalledWith( - expect.objectContaining({ body }), + await user.clear(screen.getByTestId('codemirror')); + await user.paste(VALID_BODY); + + await waitForElementToBeRemoved(() => + screen.queryByTestId('webhook-body-error'), ); + }); + + it('saves a template that is only valid JSON once rendered', async () => { + const user = userEvent.setup(); + renderForm(); + await fillIncidentIoWebhook(user, VALID_BODY); + // Outlast the debounce so a false positive would have rendered. + await act(() => new Promise(resolve => setTimeout(resolve, 400))); expect( screen.queryByTestId('webhook-body-error'), ).not.toBeInTheDocument(); + + await user.click(screen.getByTestId('add-webhook-button')); + expect(mockSaveWebhook).toHaveBeenCalledWith( + expect.objectContaining({ body: VALID_BODY }), + ); }); }); });