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..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 {
@@ -132,4 +137,65 @@ describe('WebhookForm', () => {
screen.queryByTestId('webhook-template-variables'),
).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}}"}';
+
+ 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('clears the error once the template is fixed', async () => {
+ const user = userEvent.setup();
+ renderForm();
+ await fillIncidentIoWebhook(user, ESCAPED_QUOTES_BODY);
+ await screen.findByTestId('webhook-body-error');
+
+ 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 }),
+ );
+ });
+ });
});
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')),
+ };
+ }
+}