Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .changeset/webhook-body-template-validation.md
Original file line number Diff line number Diff line change
@@ -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.
10 changes: 8 additions & 2 deletions docs/alert-webhook-template-variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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}}" },
Expand Down
Original file line number Diff line number Diff line change
@@ -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>
);
}
22 changes: 20 additions & 2 deletions packages/app/src/components/TeamSettings/WebhookForm.tsx
Original file line number Diff line number Diff line change
@@ -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,
Expand All @@ -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, {
Expand All @@ -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';

Expand Down Expand Up @@ -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;

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -418,6 +433,9 @@ export function WebhookForm({
)}
/>
</div>,
bodyError && (
Comment thread
brandon-pereira marked this conversation as resolved.
Resolved
<WebhookBodyValidationAlert key="4a" error={bodyError} />
),
<Alert
icon={<IconInfoCircleFilled size={16} />}
key="5"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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();
Comment thread
brandon-pereira marked this conversation as resolved.
Resolved

await user.click(screen.getByTestId('add-webhook-button'));
expect(mockSaveWebhook).toHaveBeenCalledWith(
expect.objectContaining({ body: VALID_BODY }),
);
});
});
});
50 changes: 50 additions & 0 deletions packages/common-utils/src/core/__tests__/handlebarsEnv.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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],
Expand Down Expand Up @@ -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);
});
});
58 changes: 58 additions & 0 deletions packages/common-utils/src/core/handlebarsEnv.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 });
Comment thread
brandon-pereira marked this conversation as resolved.
Resolved
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')),
};
}
}
Loading