@@ -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.
@@ -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}}" },
 
@@ -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 (
+    <Alert
+      variant="danger"
+      icon={<IconAlertTriangle size={16} />}
+      title={errorTitle(error)}
+      data-testid="webhook-body-error"
+    >
+      <Code block>{error.message}</Code>
+    </Alert>
+  );
+}
@@ -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({
               )}
             />
           </div>,
+          bodyError && (
+            <WebhookBodyValidationAlert key="4a" error={bodyError} />
+          ),
           <Alert
             icon={<IconInfoCircleFilled size={16} />}
             key="5"
 
@@ -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<typeof userEvent.setup>,
+      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 }),
+      );
+    });
+  });
 });
@@ -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);
+  });
+});
@@ -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')),
+    };
+  }
+}