From 894da81c34ae7e7fb27e1c63267b802d7daa2175 Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Tue, 13 Oct 2026 10:37:58 -0600 Subject: [PATCH 1/5] fix(api): reject webhook body templates that don't compile Validate generic and incident.io bodies with getWebhookTemplateError on create, update, and test across the internal API, External API v2, and MCP. Add POST /api/v2/webhooks/validate for plan-time checks. --- .../webhook-body-template-api-validation.md | 8 + docs/alert-webhook-template-variables.md | 3 +- packages/api/openapi.json | 122 +++++++++++++- packages/api/src/controllers/webhook.ts | 7 +- .../src/mcp/__tests__/webhooks.int.test.ts | 43 +++++ .../api/src/mcp/tools/alerts/saveWebhook.ts | 11 +- .../api/__tests__/webhooks.int.test.ts | 104 ++++++++++++ packages/api/src/routers/api/webhooks.ts | 15 +- .../__tests__/webhooks.int.test.ts | 138 ++++++++++++++++ .../src/routers/external-api/v2/webhooks.ts | 155 +++++++++++++++++- packages/api/src/utils/validators.ts | 38 +++++ 11 files changed, 625 insertions(+), 19 deletions(-) create mode 100644 .changeset/webhook-body-template-api-validation.md diff --git a/.changeset/webhook-body-template-api-validation.md b/.changeset/webhook-body-template-api-validation.md new file mode 100644 index 0000000000..707851f35f --- /dev/null +++ b/.changeset/webhook-body-template-api-validation.md @@ -0,0 +1,8 @@ +--- +'@hyperdx/api': patch +--- + +fix: reject generic and incident.io webhook body templates that don't compile +with a 400 on create, update, and test (internal API, External API v2, and MCP +`clickstack_save_webhook`). Add `POST /api/v2/webhooks/validate` to check a +webhook config without saving it, e.g. at Terraform plan time. diff --git a/docs/alert-webhook-template-variables.md b/docs/alert-webhook-template-variables.md index 05d1a37539..9229c1ae4c 100644 --- a/docs/alert-webhook-template-variables.md +++ b/docs/alert-webhook-template-variables.md @@ -71,7 +71,8 @@ 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. +body fails to compile, and the API rejects a body that doesn't compile when a +webhook is created, updated, or tested. 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 diff --git a/packages/api/openapi.json b/packages/api/openapi.json index 1ac293d77f..bba98b044f 100644 --- a/packages/api/openapi.json +++ b/packages/api/openapi.json @@ -5481,7 +5481,7 @@ "body": { "type": "string", "maxLength": 16384, - "description": "Optional request body template. Only for generic/incidentio; rejected for slack.", + "description": "Optional Handlebars request body template. Only for generic/incidentio; rejected for slack. Rejected with a 400 if it does not compile.", "example": "{\"alert\": \"{{title}}\", \"severity\": \"{{level}}\"}" }, "headers": { @@ -8479,6 +8479,126 @@ } } }, + "/api/v2/webhooks/validate": { + "post": { + "summary": "Validate Webhook", + "description": "Validates a webhook body against the same schema, URL rules, and body\ntemplate check used by POST /api/v2/webhooks. The webhook is **never\npersisted**. Use this endpoint at plan time (e.g. from a Terraform\nprovider) to check that a webhook configuration is valid before\napplying it. Name uniqueness is not checked.\n", + "operationId": "validateWebhook", + "tags": [ + "Webhooks" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookInput" + } + } + } + }, + "responses": { + "200": { + "description": "Validation result. HTTP 200 is always returned for valid **and**\ninvalid bodies — a non-200 response means the request itself\nfailed (auth, server error, etc.).\n", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "valid", + "errors", + "normalized" + ], + "properties": { + "valid": { + "type": "boolean", + "description": "True when the body passes all validation rules." + }, + "errors": { + "type": "array", + "description": "Validation errors. Empty when valid is true.", + "items": { + "type": "object", + "required": [ + "path", + "message" + ], + "properties": { + "path": { + "type": "string", + "description": "Dot-separated field path, or empty string for top-level errors." + }, + "message": { + "type": "string", + "description": "Human-readable error description." + } + } + } + }, + "normalized": { + "type": "object", + "nullable": true, + "description": "The parsed webhook body. Populated when valid is true,\nnull when valid is false.\n" + } + } + }, + "examples": { + "valid": { + "summary": "Valid webhook body", + "value": { + "valid": true, + "errors": [], + "normalized": { + "name": "Alerts", + "service": "generic", + "url": "https://example.com/webhooks/alerts", + "body": "{\"alert\": \"{{title}}\"}" + } + } + }, + "invalid": { + "summary": "Body template that does not compile", + "value": { + "valid": false, + "errors": [ + { + "path": "body", + "message": "Invalid webhook body template (line 1, column 12): Parse error on line 1: ..." + } + ], + "normalized": null + } + } + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + }, + "example": { + "message": "Unauthorized access. API key is missing or invalid." + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, "/api/v2/webhooks/{id}": { "put": { "summary": "Update Webhook", diff --git a/packages/api/src/controllers/webhook.ts b/packages/api/src/controllers/webhook.ts index ce791330d6..b7edf8f135 100644 --- a/packages/api/src/controllers/webhook.ts +++ b/packages/api/src/controllers/webhook.ts @@ -4,7 +4,10 @@ import Webhook, { type WebhookDocument, WebhookService, } from '@/models/webhook'; -import { validateWebhookUrl } from '@/utils/validators'; +import { + validateWebhookBodyTemplate, + validateWebhookUrl, +} from '@/utils/validators'; export interface WebhookInput { name: string; @@ -25,6 +28,7 @@ export async function createWebhook( { name, service, url, description, queryParams, headers, body }: WebhookInput, ) { validateWebhookUrl({ service, url }); + validateWebhookBodyTemplate({ service, body }); return Webhook.create({ team, @@ -61,6 +65,7 @@ export async function updateWebhook( } validateWebhookUrl({ service, url }); + validateWebhookBodyTemplate({ service, body }); const destinationChanged = url !== existing.url || service !== existing.service; diff --git a/packages/api/src/mcp/__tests__/webhooks.int.test.ts b/packages/api/src/mcp/__tests__/webhooks.int.test.ts index 239c07e0e5..5059107a8a 100644 --- a/packages/api/src/mcp/__tests__/webhooks.int.test.ts +++ b/packages/api/src/mcp/__tests__/webhooks.int.test.ts @@ -108,6 +108,33 @@ describe('MCP Webhook Tools', () => { expect(result.isError).toBe(true); }); + it('rejects a body template that does not compile', async () => { + const result = await callTool(client, 'clickstack_save_webhook', { + name: 'Broken body', + service: 'generic', + url: 'https://example.com/webhook', + body: '{"status": "{{#if (eq state \\"ALERT\\")}}firing{{/if}}"}', + }); + + expect(result.isError).toBe(true); + expect(getFirstText(result)).toContain('Invalid webhook body template'); + expect(await Webhook.countDocuments({ team: team._id })).toBe(0); + }); + + it('accepts a body template that compiles but is not JSON as written', async () => { + const body = + '{"status": "{{#if (eq state "ALERT")}}firing{{else}}resolved{{/if}}"}'; + const result = await callTool(client, 'clickstack_save_webhook', { + name: 'Conditional body', + service: 'generic', + url: 'https://example.com/webhook', + body, + }); + + expect(result.isError).toBeFalsy(); + expect((await Webhook.findOne({ team: team._id }))?.body).toBe(body); + }); + it('rejects a duplicate (team, service, name)', async () => { await Webhook.create({ team: team._id, @@ -162,6 +189,22 @@ describe('MCP Webhook Tools', () => { expect(stored?.headers?.get('X-Token')).toBe('secret'); }); + it('rejects a body template that does not compile on update', async () => { + const wh = await createGenericWebhook(); + + const result = await callTool(client, 'clickstack_save_webhook', { + id: wh._id.toString(), + name: 'Original', + service: 'generic', + url: 'https://example.com/original', + body: '{"text": "{{#if title}}"}', + }); + + expect(result.isError).toBe(true); + expect(getFirstText(result)).toContain('Invalid webhook body template'); + expect((await Webhook.findById(wh._id))?.body).toBeUndefined(); + }); + it('clears omitted write-only secrets when the destination changes', async () => { const wh = await createGenericWebhook(); diff --git a/packages/api/src/mcp/tools/alerts/saveWebhook.ts b/packages/api/src/mcp/tools/alerts/saveWebhook.ts index bbe167b3b2..f498a3d9cb 100644 --- a/packages/api/src/mcp/tools/alerts/saveWebhook.ts +++ b/packages/api/src/mcp/tools/alerts/saveWebhook.ts @@ -10,7 +10,7 @@ import { validateObjectId, } from '@/mcp/utils/errors'; import { isDuplicateKeyError } from '@/utils/errors'; -import { WebhookUrlValidationError } from '@/utils/validators'; +import { isWebhookValidationError } from '@/utils/validators'; import { externalWebhookCreateSchema } from '@/utils/zod'; // Flat z.object re-validated at runtime against externalWebhookCreateSchema: the @@ -71,8 +71,11 @@ const mcpSaveWebhookSchema = z.object({ .string() .optional() .describe( - 'Optional request body template. Not supported for the slack service. ' + - 'On update this is a full replace: omitting it clears the stored body.', + 'Optional Handlebars request body template. Not supported for the ' + + 'slack service. Rejected if it does not compile. Write string ' + + 'arguments inside {{ }} with plain or single quotes, e.g. ' + + '{{#if (eq state "ALERT")}}, never \\"ALERT\\". On update this is ' + + 'a full replace: omitting it clears the stored body.', ), }); @@ -138,7 +141,7 @@ export function registerSaveWebhook({ const webhook = await createWebhook(mongoTeamId, parsed.data); return webhookResult(webhook); } catch (e) { - if (e instanceof WebhookUrlValidationError) { + if (isWebhookValidationError(e)) { return mcpUserError(e.message); } if (isDuplicateKeyError(e)) { diff --git a/packages/api/src/routers/api/__tests__/webhooks.int.test.ts b/packages/api/src/routers/api/__tests__/webhooks.int.test.ts index 96a239fb0c..2324ecd050 100644 --- a/packages/api/src/routers/api/__tests__/webhooks.int.test.ts +++ b/packages/api/src/routers/api/__tests__/webhooks.int.test.ts @@ -620,6 +620,110 @@ describe('webhooks router', () => { }); }); + describe('Body template validation', () => { + const GENERIC_WEBHOOK = { + name: 'Generic Webhook', + service: WebhookService.Generic, + url: 'https://example.com/webhook', + }; + // Valid JSON, but `\"` inside {{ }} is not valid Handlebars. + const ESCAPED_QUOTES_BODY = + '{"status": "{{#if (eq state \\"ALERT\\")}}firing{{else}}resolved{{/if}}"}'; + // Not JSON as written, but compiles. + const CONDITIONAL_BODY = + '{"status": "{{#if (eq state "ALERT")}}firing{{else}}resolved{{/if}}"}'; + + it('POST / - rejects a body that does not compile', async () => { + const { agent } = await getLoggedInAgent(server); + + const response = await agent + .post('/webhooks') + .send({ ...GENERIC_WEBHOOK, body: ESCAPED_QUOTES_BODY }) + .expect(400); + + expect(response.body.message).toMatch( + /^Invalid webhook body template \(line 1, column 29\): Parse error/, + ); + expect(await Webhook.countDocuments({})).toBe(0); + }); + + it('POST / - rejects an incident.io body that does not compile', async () => { + const { agent } = await getLoggedInAgent(server); + + await agent + .post('/webhooks') + .send({ + ...GENERIC_WEBHOOK, + service: WebhookService.IncidentIO, + body: '{"text": "{{#if title}}"}', + }) + .expect(400); + + expect(await Webhook.countDocuments({})).toBe(0); + }); + + it('POST / - accepts a template that compiles but is not JSON as written', async () => { + const { agent } = await getLoggedInAgent(server); + + await agent + .post('/webhooks') + .send({ ...GENERIC_WEBHOOK, body: CONDITIONAL_BODY }) + .expect(200); + + expect((await Webhook.findOne({}))?.body).toBe(CONDITIONAL_BODY); + }); + + it('PUT /:id - rejects a body that does not compile', async () => { + const { agent, team } = await getLoggedInAgent(server); + const webhook = await Webhook.create({ + ...GENERIC_WEBHOOK, + body: CONDITIONAL_BODY, + team: team._id, + }); + + const response = await agent + .put(`/webhooks/${webhook._id}`) + .send({ ...GENERIC_WEBHOOK, body: ESCAPED_QUOTES_BODY }) + .expect(400); + + expect(response.body.message).toContain('Invalid webhook body template'); + expect((await Webhook.findById(webhook._id))?.body).toBe( + CONDITIONAL_BODY, + ); + }); + + it('PUT /:id - accepts a body that compiles', async () => { + const { agent, team } = await getLoggedInAgent(server); + const webhook = await Webhook.create({ + ...GENERIC_WEBHOOK, + team: team._id, + }); + + await agent + .put(`/webhooks/${webhook._id}`) + .send({ ...GENERIC_WEBHOOK, body: CONDITIONAL_BODY }) + .expect(200); + + expect((await Webhook.findById(webhook._id))?.body).toBe( + CONDITIONAL_BODY, + ); + }); + + it('POST /test - rejects a broken body without sending', async () => { + const { agent } = await getLoggedInAgent(server); + const spy = jest.spyOn(transports, 'handleSendGenericWebhook'); + + const response = await agent + .post('/webhooks/test') + .send({ ...GENERIC_WEBHOOK, body: ESCAPED_QUOTES_BODY }) + .expect(400); + + expect(response.body.message).toContain('Invalid webhook body template'); + expect(spy).not.toHaveBeenCalled(); + spy.mockRestore(); + }); + }); + describe('PUT /:id - update webhook', () => { it('updates an existing webhook', async () => { const { agent, team } = await getLoggedInAgent(server); diff --git a/packages/api/src/routers/api/webhooks.ts b/packages/api/src/routers/api/webhooks.ts index 390f9b06a9..1880938919 100644 --- a/packages/api/src/routers/api/webhooks.ts +++ b/packages/api/src/routers/api/webhooks.ts @@ -28,8 +28,9 @@ import { import type { Message } from '@/tasks/checkAlerts/transports/types'; import { isDuplicateKeyError } from '@/utils/errors'; import { + isWebhookValidationError, + validateWebhookBodyTemplate, validateWebhookUrl, - WebhookUrlValidationError, } from '@/utils/validators'; import { webhookHeaderNameSchema, @@ -122,11 +123,11 @@ const emptyToUndefined = ( ): Record | undefined => map && Object.keys(map).length > 0 ? map : undefined; -const handleWebhookUrlValidationError = ( +const handleWebhookValidationError = ( err: unknown, res: express.Response, ): boolean => { - if (!(err instanceof WebhookUrlValidationError)) return false; + if (!isWebhookValidationError(err)) return false; res.status(400).json({ message: err.message }); return true; }; @@ -211,7 +212,7 @@ router.post( data: sanitizeWebhook(serializeWebhook(webhook)), }); } catch (err) { - if (handleWebhookUrlValidationError(err, res)) return; + if (handleWebhookValidationError(err, res)) return; // Backstop the pre-flight check against a concurrent create racing on the // same (team, service, name): the unique index rejects it as a duplicate. if (isDuplicateKeyError(err)) { @@ -290,6 +291,7 @@ router.put( } validateWebhookUrl({ service, url: resolvedUrl }); + validateWebhookBodyTemplate({ service, body }); // When the URL is changing, use submitted values as-is (no merge). // An omitted field becomes undefined → $unset, so stored secrets @@ -361,7 +363,7 @@ router.put( data: sanitizeWebhook(serializeWebhook(updatedWebhook)), }); } catch (err) { - if (handleWebhookUrlValidationError(err, res)) return; + if (handleWebhookValidationError(err, res)) return; // Backstop the pre-flight check against a concurrent rename racing onto // the same (team, service, name): the unique index rejects it. if (isDuplicateKeyError(err)) { @@ -456,6 +458,7 @@ router.post( } validateWebhookUrl({ service, url }); + validateWebhookBodyTemplate({ service, body }); // Create a temporary webhook object for testing const testWebhook = new Webhook({ @@ -515,7 +518,7 @@ router.post( message: 'Test webhook sent successfully', }); } catch (err) { - if (handleWebhookUrlValidationError(err, res)) return; + if (handleWebhookValidationError(err, res)) return; next(err); } }, diff --git a/packages/api/src/routers/external-api/__tests__/webhooks.int.test.ts b/packages/api/src/routers/external-api/__tests__/webhooks.int.test.ts index 4b27c65ec7..738bca3af9 100644 --- a/packages/api/src/routers/external-api/__tests__/webhooks.int.test.ts +++ b/packages/api/src/routers/external-api/__tests__/webhooks.int.test.ts @@ -24,6 +24,13 @@ const MOCK_INCIDENT_IO_WEBHOOK = { description: 'Test webhook for incident.io', }; +// Valid JSON, but `\"` inside {{ }} is not valid Handlebars. +const ESCAPED_QUOTES_BODY = + '{"status": "{{#if (eq state \\"ALERT\\")}}firing{{/if}}"}'; +// Not JSON as written, but compiles. +const CONDITIONAL_BODY = + '{"status": "{{#if (eq state "ALERT")}}firing{{else}}resolved{{/if}}"}'; + const MOCK_GENERIC_WEBHOOK = { name: 'Test Generic Webhook', service: WebhookService.Generic, @@ -449,6 +456,36 @@ describe('External API v2 Webhooks', () => { .expect(400); }); + it('should reject a body template that does not compile', async () => { + const response = await authRequest('post', WEBHOOKS_BASE_URL) + .send({ ...MOCK_GENERIC_WEBHOOK, body: ESCAPED_QUOTES_BODY }) + .expect(400); + + expect(response.body.message).toMatch( + /^Invalid webhook body template \(line 1, column 29\): Parse error/, + ); + expect(await Webhook.countDocuments({})).toBe(0); + }); + + it('should reject an incident.io body template that does not compile', async () => { + await authRequest('post', WEBHOOKS_BASE_URL) + .send({ + ...MOCK_INCIDENT_IO_WEBHOOK, + body: '{"text": "{{#if title}}"}', + }) + .expect(400); + + expect(await Webhook.countDocuments({})).toBe(0); + }); + + it('should accept a body template that compiles but is not JSON as written', async () => { + await authRequest('post', WEBHOOKS_BASE_URL) + .send({ ...MOCK_GENERIC_WEBHOOK, body: CONDITIONAL_BODY }) + .expect(200); + + expect((await Webhook.findOne({}))?.body).toBe(CONDITIONAL_BODY); + }); + describe('field size caps', () => { it('should reject an over-long name', async () => { await authRequest('post', WEBHOOKS_BASE_URL) @@ -514,6 +551,39 @@ describe('External API v2 Webhooks', () => { }); describe('PUT /api/v2/webhooks/:id', () => { + it('should reject a body template that does not compile without updating it', async () => { + const created = await Webhook.create({ + ...MOCK_GENERIC_WEBHOOK, + team: team._id, + }); + + const response = await authRequest( + 'put', + `${WEBHOOKS_BASE_URL}/${created._id}`, + ) + .send({ ...MOCK_GENERIC_WEBHOOK, body: ESCAPED_QUOTES_BODY }) + .expect(400); + + expect(response.body.message).toContain('Invalid webhook body template'); + expect((await Webhook.findById(created._id))!.body).toBe( + MOCK_GENERIC_WEBHOOK.body, + ); + }); + + it('should accept a body template that compiles but is not JSON as written', async () => { + const created = await Webhook.create({ + ...MOCK_GENERIC_WEBHOOK, + team: team._id, + }); + + await authRequest('put', `${WEBHOOKS_BASE_URL}/${created._id}`) + .send({ ...MOCK_GENERIC_WEBHOOK, body: CONDITIONAL_BODY }) + .expect(200); + + expect((await Webhook.findById(created._id))!.body).toBe( + CONDITIONAL_BODY, + ); + }); it('should reject a private webhook URL without updating it', async () => { const created = await Webhook.create({ ...MOCK_GENERIC_WEBHOOK, @@ -791,6 +861,74 @@ describe('External API v2 Webhooks', () => { }); }); + describe('POST /api/v2/webhooks/validate', () => { + const VALIDATE_URL = `${WEBHOOKS_BASE_URL}/validate`; + + it('should return valid with the normalized body for a valid webhook', async () => { + const response = await authRequest('post', VALIDATE_URL) + .send({ ...MOCK_GENERIC_WEBHOOK, body: CONDITIONAL_BODY }) + .expect(200); + + expect(response.body).toEqual({ + valid: true, + errors: [], + normalized: { ...MOCK_GENERIC_WEBHOOK, body: CONDITIONAL_BODY }, + }); + expect(await Webhook.countDocuments({})).toBe(0); + }); + + it('should report a body template that does not compile', async () => { + const response = await authRequest('post', VALIDATE_URL) + .send({ ...MOCK_GENERIC_WEBHOOK, body: ESCAPED_QUOTES_BODY }) + .expect(200); + + expect(response.body.valid).toBe(false); + expect(response.body.normalized).toBeNull(); + expect(response.body.errors).toEqual([ + { + path: 'body', + message: expect.stringMatching( + /^Invalid webhook body template \(line 1, column 29\)/, + ), + }, + ]); + }); + + it('should report URL and body errors together', async () => { + const response = await authRequest('post', VALIDATE_URL) + .send({ + ...MOCK_GENERIC_WEBHOOK, + url: 'http://[fd00::1]/webhook', + body: ESCAPED_QUOTES_BODY, + }) + .expect(200); + + expect(response.body.valid).toBe(false); + expect(response.body.errors.map((e: { path: string }) => e.path)).toEqual( + ['url', 'body'], + ); + }); + + it('should report schema errors with their path', async () => { + const response = await authRequest('post', VALIDATE_URL) + .send({ ...MOCK_SLACK_WEBHOOK, name: undefined }) + .expect(200); + + expect(response.body.valid).toBe(false); + expect(response.body.normalized).toBeNull(); + expect(response.body.errors).toEqual( + expect.arrayContaining([expect.objectContaining({ path: 'name' })]), + ); + }); + + it('should require authentication', async () => { + await request(server.getHttpServer()) + .post(VALIDATE_URL) + .send(MOCK_SLACK_WEBHOOK) + .expect(401); + }); + }); + describe('DELETE /api/v2/webhooks/:id', () => { it('should delete a webhook', async () => { const created = await Webhook.create({ diff --git a/packages/api/src/routers/external-api/v2/webhooks.ts b/packages/api/src/routers/external-api/v2/webhooks.ts index 99c1e8b946..caf8a181d2 100644 --- a/packages/api/src/routers/external-api/v2/webhooks.ts +++ b/packages/api/src/routers/external-api/v2/webhooks.ts @@ -17,7 +17,11 @@ import { paginationMeta, paginationQuerySchema, } from '@/utils/pagination'; -import { WebhookUrlValidationError } from '@/utils/validators'; +import { + isWebhookValidationError, + validateWebhookBodyTemplate, + validateWebhookUrl, +} from '@/utils/validators'; import { ExternalWebhook, externalWebhookCreateSchema, @@ -28,15 +32,28 @@ import { const DUPLICATE_WEBHOOK_MESSAGE = 'A webhook with this service and name already exists'; -const handleWebhookUrlValidationError = ( +const handleWebhookValidationError = ( err: unknown, res: express.Response, ): boolean => { - if (!(err instanceof WebhookUrlValidationError)) return false; + if (!isWebhookValidationError(err)) return false; res.status(400).json({ message: err.message }); return true; }; +const collectValidationError = ( + path: string, + check: () => void, +): { path: string; message: string }[] => { + try { + check(); + return []; + } catch (err) { + if (!isWebhookValidationError(err)) throw err; + return [{ path, message: err.message }]; + } +}; + // Countable log event (see agent_docs/observability.md): a webhook that was // written but can't be serialized back to the client. `service` is a // low-cardinality enum (slack/incidentio/generic). @@ -407,7 +424,7 @@ router.get( * body: * type: string * maxLength: 16384 - * description: Optional request body template. Only for generic/incidentio; rejected for slack. + * description: Optional Handlebars request body template. Only for generic/incidentio; rejected for slack. Rejected with a 400 if it does not compile. * example: '{"alert": "{{title}}", "severity": "{{level}}"}' * headers: * type: object @@ -433,6 +450,132 @@ router.get( * description: The webhook object. */ +/** + * @openapi + * /api/v2/webhooks/validate: + * post: + * summary: Validate Webhook + * description: | + * Validates a webhook body against the same schema, URL rules, and body + * template check used by POST /api/v2/webhooks. The webhook is **never + * persisted**. Use this endpoint at plan time (e.g. from a Terraform + * provider) to check that a webhook configuration is valid before + * applying it. Name uniqueness is not checked. + * operationId: validateWebhook + * tags: [Webhooks] + * requestBody: + * required: true + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/WebhookInput' + * responses: + * '200': + * description: | + * Validation result. HTTP 200 is always returned for valid **and** + * invalid bodies — a non-200 response means the request itself + * failed (auth, server error, etc.). + * content: + * application/json: + * schema: + * type: object + * required: [valid, errors, normalized] + * properties: + * valid: + * type: boolean + * description: True when the body passes all validation rules. + * errors: + * type: array + * description: Validation errors. Empty when valid is true. + * items: + * type: object + * required: [path, message] + * properties: + * path: + * type: string + * description: Dot-separated field path, or empty string for top-level errors. + * message: + * type: string + * description: Human-readable error description. + * normalized: + * type: object + * nullable: true + * description: | + * The parsed webhook body. Populated when valid is true, + * null when valid is false. + * examples: + * valid: + * summary: Valid webhook body + * value: + * valid: true + * errors: [] + * normalized: + * name: "Alerts" + * service: "generic" + * url: "https://example.com/webhooks/alerts" + * body: '{"alert": "{{title}}"}' + * invalid: + * summary: Body template that does not compile + * value: + * valid: false + * errors: + * - path: "body" + * message: "Invalid webhook body template (line 1, column 12): Parse error on line 1: ..." + * normalized: null + * '401': + * description: Unauthorized + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' + * example: + * message: "Unauthorized access. API key is missing or invalid." + * '403': + * description: Forbidden + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' + */ +router.post('/validate', async (req, res, next) => { + try { + const teamId = req.user?.team; + if (teamId == null) { + return res.status(403).json({ message: 'Forbidden' }); + } + + const parsed = externalWebhookCreateSchema.safeParse(req.body); + if (!parsed.success) { + return res.json({ + valid: false, + errors: parsed.error.issues.map(i => ({ + path: i.path.join('.'), + message: i.message, + })), + normalized: null, + }); + } + + const { service, url, body } = parsed.data; + const errors = [ + ...collectValidationError('url', () => + validateWebhookUrl({ service, url }), + ), + ...collectValidationError('body', () => + validateWebhookBodyTemplate({ service, body }), + ), + ]; + + return res.json({ + valid: errors.length === 0, + errors, + normalized: errors.length === 0 ? parsed.data : null, + }); + } catch (e) { + next(e); + } +}); + /** * @openapi * /api/v2/webhooks: @@ -503,7 +646,7 @@ router.post( res.json({ data }); } catch (e) { - if (handleWebhookUrlValidationError(e, res)) return; + if (handleWebhookValidationError(e, res)) return; if (isDuplicateKeyError(e)) { return res.status(400).json({ message: DUPLICATE_WEBHOOK_MESSAGE }); } @@ -623,7 +766,7 @@ router.put( res.json({ data }); } catch (e) { - if (handleWebhookUrlValidationError(e, res)) return; + if (handleWebhookValidationError(e, res)) return; if (isDuplicateKeyError(e)) { return res.status(400).json({ message: DUPLICATE_WEBHOOK_MESSAGE }); } diff --git a/packages/api/src/utils/validators.ts b/packages/api/src/utils/validators.ts index 0cc6fe169b..34247d680e 100644 --- a/packages/api/src/utils/validators.ts +++ b/packages/api/src/utils/validators.ts @@ -1,3 +1,4 @@ +import { getWebhookTemplateError } from '@hyperdx/common-utils/dist/core/handlebarsEnv'; import { WebhookService } from '@hyperdx/common-utils/dist/types'; import { isValidSlackUrl, @@ -165,6 +166,43 @@ export function validateWebhookUrl( } } +export class WebhookBodyValidationError extends Error { + constructor(message: string) { + super(message); + this.name = 'WebhookBodyValidationError'; + } +} + +/** + * Rejects a body template Handlebars cannot compile, which would otherwise + * fail on every alert delivery. Slack never renders the body. + */ +export function validateWebhookBodyTemplate({ + service, + body, +}: { + service: WebhookService; + body?: string; +}) { + if (service === WebhookService.Slack) return; + const error = getWebhookTemplateError(body); + if (error == null) return; + const location = + error.line == null + ? '' + : ` (line ${error.line}${error.column == null ? '' : `, column ${error.column}`})`; + throw new WebhookBodyValidationError( + `Invalid webhook body template${location}: ${error.message}`, + ); +} + +/** A 400-worthy webhook config error whose message is safe to return. */ +export const isWebhookValidationError = ( + err: unknown, +): err is WebhookUrlValidationError | WebhookBodyValidationError => + err instanceof WebhookUrlValidationError || + err instanceof WebhookBodyValidationError; + export const passwordSchema = z .string() .min( From 137ef8a08240c085cab7f9243d16e4188cc6213e Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Wed, 14 Oct 2026 08:47:14 -0600 Subject: [PATCH 2/5] refactor(api): share webhook config checks between create and /validate --- packages/api/src/controllers/webhook.ts | 11 +--- packages/api/src/routers/api/webhooks.ts | 9 +-- .../src/routers/external-api/v2/webhooks.ts | 26 +------- .../src/utils/__tests__/validators.test.ts | 66 +++++++++++++++++++ packages/api/src/utils/validators.ts | 34 +++++++++- 5 files changed, 107 insertions(+), 39 deletions(-) diff --git a/packages/api/src/controllers/webhook.ts b/packages/api/src/controllers/webhook.ts index b7edf8f135..a37f41fcbe 100644 --- a/packages/api/src/controllers/webhook.ts +++ b/packages/api/src/controllers/webhook.ts @@ -4,10 +4,7 @@ import Webhook, { type WebhookDocument, WebhookService, } from '@/models/webhook'; -import { - validateWebhookBodyTemplate, - validateWebhookUrl, -} from '@/utils/validators'; +import { validateWebhookConfig } from '@/utils/validators'; export interface WebhookInput { name: string; @@ -27,8 +24,7 @@ export async function createWebhook( team: ObjectId | string, { name, service, url, description, queryParams, headers, body }: WebhookInput, ) { - validateWebhookUrl({ service, url }); - validateWebhookBodyTemplate({ service, body }); + validateWebhookConfig({ service, url, body }); return Webhook.create({ team, @@ -64,8 +60,7 @@ export async function updateWebhook( return { status: 'not_found' }; } - validateWebhookUrl({ service, url }); - validateWebhookBodyTemplate({ service, body }); + validateWebhookConfig({ service, url, body }); const destinationChanged = url !== existing.url || service !== existing.service; diff --git a/packages/api/src/routers/api/webhooks.ts b/packages/api/src/routers/api/webhooks.ts index 1880938919..db9bdb80b7 100644 --- a/packages/api/src/routers/api/webhooks.ts +++ b/packages/api/src/routers/api/webhooks.ts @@ -29,8 +29,7 @@ import type { Message } from '@/tasks/checkAlerts/transports/types'; import { isDuplicateKeyError } from '@/utils/errors'; import { isWebhookValidationError, - validateWebhookBodyTemplate, - validateWebhookUrl, + validateWebhookConfig, } from '@/utils/validators'; import { webhookHeaderNameSchema, @@ -290,8 +289,7 @@ router.put( }); } - validateWebhookUrl({ service, url: resolvedUrl }); - validateWebhookBodyTemplate({ service, body }); + validateWebhookConfig({ service, url: resolvedUrl, body }); // When the URL is changing, use submitted values as-is (no merge). // An omitted field becomes undefined → $unset, so stored secrets @@ -457,8 +455,7 @@ router.post( } } - validateWebhookUrl({ service, url }); - validateWebhookBodyTemplate({ service, body }); + validateWebhookConfig({ service, url, body }); // Create a temporary webhook object for testing const testWebhook = new Webhook({ diff --git a/packages/api/src/routers/external-api/v2/webhooks.ts b/packages/api/src/routers/external-api/v2/webhooks.ts index caf8a181d2..780b60e513 100644 --- a/packages/api/src/routers/external-api/v2/webhooks.ts +++ b/packages/api/src/routers/external-api/v2/webhooks.ts @@ -18,9 +18,8 @@ import { paginationQuerySchema, } from '@/utils/pagination'; import { + getWebhookConfigErrors, isWebhookValidationError, - validateWebhookBodyTemplate, - validateWebhookUrl, } from '@/utils/validators'; import { ExternalWebhook, @@ -41,19 +40,6 @@ const handleWebhookValidationError = ( return true; }; -const collectValidationError = ( - path: string, - check: () => void, -): { path: string; message: string }[] => { - try { - check(); - return []; - } catch (err) { - if (!isWebhookValidationError(err)) throw err; - return [{ path, message: err.message }]; - } -}; - // Countable log event (see agent_docs/observability.md): a webhook that was // written but can't be serialized back to the client. `service` is a // low-cardinality enum (slack/incidentio/generic). @@ -556,15 +542,7 @@ router.post('/validate', async (req, res, next) => { }); } - const { service, url, body } = parsed.data; - const errors = [ - ...collectValidationError('url', () => - validateWebhookUrl({ service, url }), - ), - ...collectValidationError('body', () => - validateWebhookBodyTemplate({ service, body }), - ), - ]; + const errors = getWebhookConfigErrors(parsed.data); return res.json({ valid: errors.length === 0, diff --git a/packages/api/src/utils/__tests__/validators.test.ts b/packages/api/src/utils/__tests__/validators.test.ts index f9f42d1387..b73ac76dd3 100644 --- a/packages/api/src/utils/__tests__/validators.test.ts +++ b/packages/api/src/utils/__tests__/validators.test.ts @@ -317,6 +317,72 @@ describe('validators', () => { }); }); + describe('getWebhookConfigErrors', () => { + const BROKEN_BODY = '{"text": "{{#if title}}"}'; + + it('returns no errors for a valid config', () => { + expect( + validators.getWebhookConfigErrors({ + service: WebhookService.Generic, + url: 'https://example.com/webhook', + body: '{"status": "{{#if (eq state "ALERT")}}firing{{/if}}"}', + }), + ).toEqual([]); + }); + + it('reports URL and body errors with their paths', () => { + expect( + validators.getWebhookConfigErrors({ + service: WebhookService.Generic, + url: 'http://127.0.0.1/webhook', + body: BROKEN_BODY, + }), + ).toEqual([ + { + path: 'url', + message: expect.stringContaining('private or reserved'), + }, + { + path: 'body', + message: expect.stringMatching( + /^Invalid webhook body template \(line 1, column 26\): Parse error/, + ), + }, + ]); + }); + + it.each([ + [ + 'a slack webhook', + WebhookService.Slack, + 'https://hooks.slack.com/services/T0/B0/X', + BROKEN_BODY, + ], + [ + 'an empty body', + WebhookService.Generic, + 'https://example.com/webhook', + ' ', + ], + ])('skips the body check for %s', (_label, service, url, body) => { + expect(validators.getWebhookConfigErrors({ service, url, body })).toEqual( + [], + ); + }); + }); + + describe('validateWebhookConfig', () => { + it('throws the same error create returns as a 400', () => { + expect(() => + validators.validateWebhookConfig({ + service: WebhookService.IncidentIO, + url: 'https://example.com/webhook', + body: '{"text": "{{#if title}}"}', + }), + ).toThrow(validators.WebhookBodyValidationError); + }); + }); + describe('validatePassword', () => { it('should return true if password is valid', () => { expect(validators.validatePassword('aB3!efghijkl')).toBe(true); diff --git a/packages/api/src/utils/validators.ts b/packages/api/src/utils/validators.ts index 34247d680e..cac0fbb529 100644 --- a/packages/api/src/utils/validators.ts +++ b/packages/api/src/utils/validators.ts @@ -177,7 +177,7 @@ export class WebhookBodyValidationError extends Error { * Rejects a body template Handlebars cannot compile, which would otherwise * fail on every alert delivery. Slack never renders the body. */ -export function validateWebhookBodyTemplate({ +function validateWebhookBodyTemplate({ service, body, }: { @@ -203,6 +203,38 @@ export const isWebhookValidationError = ( err instanceof WebhookUrlValidationError || err instanceof WebhookBodyValidationError; +type WebhookConfigInput = WebhookUrlInput & { body?: string }; + +// The one list of checks a webhook must pass before it is saved or sent, so +// POST /api/v2/webhooks/validate can never pass a config that create rejects. +const WEBHOOK_CONFIG_CHECKS: { + path: string; + check: (input: WebhookConfigInput) => void; +}[] = [ + { path: 'url', check: input => validateWebhookUrl(input) }, + { path: 'body', check: input => validateWebhookBodyTemplate(input) }, +]; + +/** Throws the first webhook config error. */ +export function validateWebhookConfig(input: WebhookConfigInput) { + for (const { check } of WEBHOOK_CONFIG_CHECKS) check(input); +} + +/** Returns every webhook config error instead of throwing the first. */ +export function getWebhookConfigErrors( + input: WebhookConfigInput, +): { path: string; message: string }[] { + return WEBHOOK_CONFIG_CHECKS.flatMap(({ path, check }) => { + try { + check(input); + return []; + } catch (err) { + if (!isWebhookValidationError(err)) throw err; + return [{ path, message: err.message }]; + } + }); +} + export const passwordSchema = z .string() .min( From a9a4bd7a6ee1c6e4877cf6d43ede8340a081f298 Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Wed, 14 Oct 2026 09:25:50 -0600 Subject: [PATCH 3/5] fix(api): reject unknown webhook body helpers, strip secrets from /validate normalized --- .../webhook-body-template-api-validation.md | 5 +- docs/alert-webhook-template-variables.md | 5 +- packages/api/openapi.json | 4 +- .../api/src/mcp/tools/alerts/saveWebhook.ts | 3 +- .../__tests__/webhooks.int.test.ts | 32 +++++++- .../src/routers/external-api/v2/webhooks.ts | 15 +++- .../src/utils/__tests__/validators.test.ts | 53 ++++++++++++++ packages/api/src/utils/validators.ts | 73 ++++++++++++++++++- 8 files changed, 172 insertions(+), 18 deletions(-) diff --git a/.changeset/webhook-body-template-api-validation.md b/.changeset/webhook-body-template-api-validation.md index 707851f35f..11880a9d8e 100644 --- a/.changeset/webhook-body-template-api-validation.md +++ b/.changeset/webhook-body-template-api-validation.md @@ -2,7 +2,8 @@ '@hyperdx/api': patch --- -fix: reject generic and incident.io webhook body templates that don't compile -with a 400 on create, update, and test (internal API, External API v2, and MCP +fix: reject generic and incident.io webhook body templates that don't compile, +or that call a helper delivery doesn't register (e.g. a typo for `eq`), with a +400 on create, update, and test (internal API, External API v2, and MCP `clickstack_save_webhook`). Add `POST /api/v2/webhooks/validate` to check a webhook config without saving it, e.g. at Terraform plan time. diff --git a/docs/alert-webhook-template-variables.md b/docs/alert-webhook-template-variables.md index 9229c1ae4c..7443a8ea57 100644 --- a/docs/alert-webhook-template-variables.md +++ b/docs/alert-webhook-template-variables.md @@ -71,8 +71,9 @@ 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, and the API rejects a body that doesn't compile when a -webhook is created, updated, or tested. +body fails to compile. The API rejects a body that doesn't compile, or that +calls a helper other than `eq` and the Handlebars built-ins, when a webhook is +created, updated, or tested. 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 diff --git a/packages/api/openapi.json b/packages/api/openapi.json index bba98b044f..30ff03cf14 100644 --- a/packages/api/openapi.json +++ b/packages/api/openapi.json @@ -5481,7 +5481,7 @@ "body": { "type": "string", "maxLength": 16384, - "description": "Optional Handlebars request body template. Only for generic/incidentio; rejected for slack. Rejected with a 400 if it does not compile.", + "description": "Optional Handlebars request body template. Only for generic/incidentio; rejected for slack. Rejected with a 400 if it does not compile or calls a helper other than `eq` and the Handlebars built-ins.", "example": "{\"alert\": \"{{title}}\", \"severity\": \"{{level}}\"}" }, "headers": { @@ -8538,7 +8538,7 @@ "normalized": { "type": "object", "nullable": true, - "description": "The parsed webhook body. Populated when valid is true,\nnull when valid is false.\n" + "description": "The parsed webhook body, without the write-only\n`headers` and `queryParams`. Populated when valid is\ntrue, null when valid is false.\n" } } }, diff --git a/packages/api/src/mcp/tools/alerts/saveWebhook.ts b/packages/api/src/mcp/tools/alerts/saveWebhook.ts index f498a3d9cb..e8e33590f7 100644 --- a/packages/api/src/mcp/tools/alerts/saveWebhook.ts +++ b/packages/api/src/mcp/tools/alerts/saveWebhook.ts @@ -72,7 +72,8 @@ const mcpSaveWebhookSchema = z.object({ .optional() .describe( 'Optional Handlebars request body template. Not supported for the ' + - 'slack service. Rejected if it does not compile. Write string ' + + 'slack service. Rejected if it does not compile or calls a helper ' + + 'other than eq and the Handlebars built-ins. Write string ' + 'arguments inside {{ }} with plain or single quotes, e.g. ' + '{{#if (eq state "ALERT")}}, never \\"ALERT\\". On update this is ' + 'a full replace: omitting it clears the stored body.', diff --git a/packages/api/src/routers/external-api/__tests__/webhooks.int.test.ts b/packages/api/src/routers/external-api/__tests__/webhooks.int.test.ts index 738bca3af9..60ec86ef90 100644 --- a/packages/api/src/routers/external-api/__tests__/webhooks.int.test.ts +++ b/packages/api/src/routers/external-api/__tests__/webhooks.int.test.ts @@ -864,15 +864,20 @@ describe('External API v2 Webhooks', () => { describe('POST /api/v2/webhooks/validate', () => { const VALIDATE_URL = `${WEBHOOKS_BASE_URL}/validate`; - it('should return valid with the normalized body for a valid webhook', async () => { + it('should return valid with the normalized body, minus write-only secrets', async () => { const response = await authRequest('post', VALIDATE_URL) - .send({ ...MOCK_GENERIC_WEBHOOK, body: CONDITIONAL_BODY }) + .send({ + ...MOCK_GENERIC_WEBHOOK, + queryParams: { token: 'secret' }, + body: CONDITIONAL_BODY, + }) .expect(200); + const { headers: _headers, ...readable } = MOCK_GENERIC_WEBHOOK; expect(response.body).toEqual({ valid: true, errors: [], - normalized: { ...MOCK_GENERIC_WEBHOOK, body: CONDITIONAL_BODY }, + normalized: { ...readable, body: CONDITIONAL_BODY }, }); expect(await Webhook.countDocuments({})).toBe(0); }); @@ -894,6 +899,27 @@ describe('External API v2 Webhooks', () => { ]); }); + it('should report a call to a helper delivery does not register', async () => { + const response = await authRequest('post', VALIDATE_URL) + .send({ + ...MOCK_GENERIC_WEBHOOK, + body: '{"s": "{{#if (equals state "ALERT")}}x{{/if}}"}', + }) + .expect(200); + + expect(response.body).toEqual({ + valid: false, + errors: [ + { + path: 'body', + message: + 'Invalid webhook body template (line 1, column 15): Unknown helper "equals"', + }, + ], + normalized: null, + }); + }); + it('should report URL and body errors together', async () => { const response = await authRequest('post', VALIDATE_URL) .send({ diff --git a/packages/api/src/routers/external-api/v2/webhooks.ts b/packages/api/src/routers/external-api/v2/webhooks.ts index 780b60e513..479334e13e 100644 --- a/packages/api/src/routers/external-api/v2/webhooks.ts +++ b/packages/api/src/routers/external-api/v2/webhooks.ts @@ -410,7 +410,7 @@ router.get( * body: * type: string * maxLength: 16384 - * description: Optional Handlebars request body template. Only for generic/incidentio; rejected for slack. Rejected with a 400 if it does not compile. + * description: Optional Handlebars request body template. Only for generic/incidentio; rejected for slack. Rejected with a 400 if it does not compile or calls a helper other than `eq` and the Handlebars built-ins. * example: '{"alert": "{{title}}", "severity": "{{level}}"}' * headers: * type: object @@ -487,8 +487,9 @@ router.get( * type: object * nullable: true * description: | - * The parsed webhook body. Populated when valid is true, - * null when valid is false. + * The parsed webhook body, without the write-only + * `headers` and `queryParams`. Populated when valid is + * true, null when valid is false. * examples: * valid: * summary: Valid webhook body @@ -543,11 +544,17 @@ router.post('/validate', async (req, res, next) => { } const errors = getWebhookConfigErrors(parsed.data); + // Never echo write-only secrets, matching every other webhook read path. + const { + headers: _headers, + queryParams: _queryParams, + ...readable + } = parsed.data; return res.json({ valid: errors.length === 0, errors, - normalized: errors.length === 0 ? parsed.data : null, + normalized: errors.length === 0 ? readable : null, }); } catch (e) { next(e); diff --git a/packages/api/src/utils/__tests__/validators.test.ts b/packages/api/src/utils/__tests__/validators.test.ts index b73ac76dd3..c8c341574d 100644 --- a/packages/api/src/utils/__tests__/validators.test.ts +++ b/packages/api/src/utils/__tests__/validators.test.ts @@ -1,5 +1,6 @@ import { WebhookService } from '@hyperdx/common-utils/dist/types'; +import { createHandlebarsWithHelpers } from '@/tasks/checkAlerts/transports'; import * as validators from '@/utils/validators'; describe('validators', () => { @@ -351,6 +352,58 @@ describe('validators', () => { ]); }); + it.each([ + ['a top-level call', '{"s": "{{equals state "ALERT"}}"}', 10], + [ + 'a subexpression', + '{"s": "{{#if (equals state "ALERT")}}x{{/if}}"}', + 15, + ], + ['a block call', '{"s": "{{#equals state "ALERT"}}x{{/equals}}"}', 11], + [ + 'a call in a branch a sample alert would skip', + '{"s": "{{#if (eq state "OK")}}{{equals a b}}{{/if}}"}', + 33, + ], + ])('rejects an unknown helper in %s', (_label, body, column) => { + expect( + validators.getWebhookConfigErrors({ + service: WebhookService.Generic, + url: 'https://example.com/webhook', + body, + }), + ).toEqual([ + { + path: 'body', + message: `Invalid webhook body template (line 1, column ${column}): Unknown helper "equals"`, + }, + ]); + }); + + it('knows exactly the helpers delivery registers', () => { + const delivery = Object.keys( + createHandlebarsWithHelpers().helpers, + ).filter( + name => name !== 'helperMissing' && name !== 'blockHelperMissing', + ); + expect([...validators.WEBHOOK_BODY_HELPERS].sort()).toEqual( + delivery.sort(), + ); + }); + + it('accepts registered helpers and bare lookups', () => { + expect( + validators.getWebhookConfigErrors({ + service: WebhookService.Generic, + url: 'https://example.com/webhook', + body: + '{"a": "{{#if (eq state "ALERT")}}{{title}}{{/if}}", ' + + '"b": "{{#each tags}}{{this}}{{/each}}{{lookup this "title"}}", ' + + '"c": "{{#unless value}}{{missing}}{{/unless}}{{#section}}x{{/section}}"}', + }), + ).toEqual([]); + }); + it.each([ [ 'a slack webhook', diff --git a/packages/api/src/utils/validators.ts b/packages/api/src/utils/validators.ts index cac0fbb529..5ac9cc09a3 100644 --- a/packages/api/src/utils/validators.ts +++ b/packages/api/src/utils/validators.ts @@ -1,4 +1,7 @@ -import { getWebhookTemplateError } from '@hyperdx/common-utils/dist/core/handlebarsEnv'; +import { + getWebhookTemplateError, + type WebhookTemplateError, +} from '@hyperdx/common-utils/dist/core/handlebarsEnv'; import { WebhookService } from '@hyperdx/common-utils/dist/types'; import { isValidSlackUrl, @@ -7,6 +10,7 @@ import { PASSWORD_SPECIAL_CHARS, passwordValidators, } from '@hyperdx/common-utils/dist/validation'; +import Handlebars from 'handlebars'; import { Address4, Address6 } from 'ip-address'; import { z } from 'zod'; @@ -174,8 +178,67 @@ export class WebhookBodyValidationError extends Error { } /** - * Rejects a body template Handlebars cannot compile, which would otherwise - * fail on every alert delivery. Slack never renders the body. + * Helpers alert delivery registers (`createHandlebarsWithHelpers` in + * tasks/checkAlerts/transports/generic.ts). Listed here rather than imported + * because generic.ts imports this module; a unit test pins the two together. + */ +export const WEBHOOK_BODY_HELPERS = new Set([ + 'eq', + 'if', + 'unless', + 'each', + 'with', + 'lookup', + 'log', +]); + +type HelperCall = + | hbs.AST.MustacheStatement + | hbs.AST.BlockStatement + | hbs.AST.SubExpression; + +/** + * Finds the first call with arguments to a helper delivery doesn't register. + * Handlebars throws "Missing helper" for those only when the call renders, so + * a typo inside an untaken branch would pass a test render; walk the AST. + */ +function findUnknownHelperCall(template: string): WebhookTemplateError | null { + let found: WebhookTemplateError | null = null; + const check = (node: HelperCall) => { + if (found != null || node.params.length === 0) return; + const { path } = node; + const name = 'original' in path ? String(path.original) : path.type; + if (path.type === 'PathExpression' && WEBHOOK_BODY_HELPERS.has(name)) + return; + found = { + message: `Unknown helper "${name}"`, + line: path.loc.start.line, + column: path.loc.start.column + 1, + }; + }; + + class HelperCallVisitor extends Handlebars.Visitor { + MustacheStatement(node: hbs.AST.MustacheStatement) { + check(node); + super.MustacheStatement(node); + } + BlockStatement(node: hbs.AST.BlockStatement) { + check(node); + super.BlockStatement(node); + } + SubExpression(node: hbs.AST.SubExpression) { + check(node); + super.SubExpression(node); + } + } + new HelperCallVisitor().accept(Handlebars.parse(template)); + return found; +} + +/** + * Rejects a body template that would fail on every alert delivery: one + * Handlebars cannot compile, or one that calls a helper delivery doesn't + * register. Slack never renders the body. */ function validateWebhookBodyTemplate({ service, @@ -185,7 +248,9 @@ function validateWebhookBodyTemplate({ body?: string; }) { if (service === WebhookService.Slack) return; - const error = getWebhookTemplateError(body); + const error = + getWebhookTemplateError(body) ?? + (body?.trim() ? findUnknownHelperCall(body) : null); if (error == null) return; const location = error.line == null From 1f91d58b5cf95c4f7a50c0c57e0daf0cef57fe13 Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Wed, 14 Oct 2026 09:38:09 -0600 Subject: [PATCH 4/5] fix(api): reject undefined partials and decorators in webhook bodies (deep-review P2) --- .../api/__tests__/webhooks.int.test.ts | 17 ++++ .../src/utils/__tests__/validators.test.ts | 28 ++++++ packages/api/src/utils/validators.ts | 93 ++++++++++++++----- 3 files changed, 117 insertions(+), 21 deletions(-) diff --git a/packages/api/src/routers/api/__tests__/webhooks.int.test.ts b/packages/api/src/routers/api/__tests__/webhooks.int.test.ts index 2324ecd050..55520e121f 100644 --- a/packages/api/src/routers/api/__tests__/webhooks.int.test.ts +++ b/packages/api/src/routers/api/__tests__/webhooks.int.test.ts @@ -662,6 +662,23 @@ describe('webhooks router', () => { expect(await Webhook.countDocuments({})).toBe(0); }); + it('POST / - rejects a call to a helper delivery does not register', async () => { + const { agent } = await getLoggedInAgent(server); + + const response = await agent + .post('/webhooks') + .send({ + ...GENERIC_WEBHOOK, + body: '{"s": "{{#if (equals state "ALERT")}}x{{/if}}"}', + }) + .expect(400); + + expect(response.body.message).toBe( + 'Invalid webhook body template (line 1, column 15): Unknown helper "equals"', + ); + expect(await Webhook.countDocuments({})).toBe(0); + }); + it('POST / - accepts a template that compiles but is not JSON as written', async () => { const { agent } = await getLoggedInAgent(server); diff --git a/packages/api/src/utils/__tests__/validators.test.ts b/packages/api/src/utils/__tests__/validators.test.ts index c8c341574d..ac7842fd2e 100644 --- a/packages/api/src/utils/__tests__/validators.test.ts +++ b/packages/api/src/utils/__tests__/validators.test.ts @@ -380,6 +380,34 @@ describe('validators', () => { ]); }); + it.each([ + ['a partial', '{"a": "{{> foo}}"}', 'Unknown partial "foo"'], + ['a decorator', '{"a": "{{* foo}}"}', 'Unknown decorator "foo"'], + [ + 'a block decorator other than inline', + '{"a": "{{#* foo}}x{{/foo}}"}', + 'Unknown decorator "foo"', + ], + ])('rejects %s delivery does not provide', (_label, body, message) => { + expect( + validators.getWebhookConfigErrors({ + service: WebhookService.Generic, + url: 'https://example.com/webhook', + body, + }), + ).toEqual([{ path: 'body', message: expect.stringContaining(message) }]); + }); + + it('accepts a partial block fallback and an inline partial', () => { + expect( + validators.getWebhookConfigErrors({ + service: WebhookService.Generic, + url: 'https://example.com/webhook', + body: '{"a": "{{#> foo}}x{{/foo}}", "b": "{{#* inline "p"}}y{{/inline}}{{> p}}"}', + }), + ).toEqual([]); + }); + it('knows exactly the helpers delivery registers', () => { const delivery = Object.keys( createHandlebarsWithHelpers().helpers, diff --git a/packages/api/src/utils/validators.ts b/packages/api/src/utils/validators.ts index 5ac9cc09a3..fb445a92b5 100644 --- a/packages/api/src/utils/validators.ts +++ b/packages/api/src/utils/validators.ts @@ -197,48 +197,99 @@ type HelperCall = | hbs.AST.BlockStatement | hbs.AST.SubExpression; +const toError = ( + message: string, + node: hbs.AST.Node, +): WebhookTemplateError => ({ + message, + line: node.loc.start.line, + column: node.loc.start.column + 1, +}); + +const nameOf = (node: hbs.AST.Expression): string => + 'original' in node ? String(node.original) : node.type; + /** - * Finds the first call with arguments to a helper delivery doesn't register. - * Handlebars throws "Missing helper" for those only when the call renders, so - * a typo inside an untaken branch would pass a test render; walk the AST. + * Finds the first construct that compiles but throws on every delivery: a + * call with arguments to a helper delivery doesn't register, a partial the + * template doesn't define inline, or a decorator other than `inline`. + * Handlebars only throws for these when they render, so a typo inside an + * untaken branch would pass a test render; walk the AST instead. */ -function findUnknownHelperCall(template: string): WebhookTemplateError | null { +function findUndeliverableConstruct( + template: string, +): WebhookTemplateError | null { let found: WebhookTemplateError | null = null; - const check = (node: HelperCall) => { + const inlinePartials = new Set(); + const partialRefs: hbs.AST.PartialStatement[] = []; + + const checkHelperCall = (node: HelperCall) => { if (found != null || node.params.length === 0) return; const { path } = node; - const name = 'original' in path ? String(path.original) : path.type; - if (path.type === 'PathExpression' && WEBHOOK_BODY_HELPERS.has(name)) + if ( + path.type === 'PathExpression' && + WEBHOOK_BODY_HELPERS.has(nameOf(path)) + ) return; - found = { - message: `Unknown helper "${name}"`, - line: path.loc.start.line, - column: path.loc.start.column + 1, - }; + found = toError(`Unknown helper "${nameOf(path)}"`, path); }; - class HelperCallVisitor extends Handlebars.Visitor { + class Visitor extends Handlebars.Visitor { MustacheStatement(node: hbs.AST.MustacheStatement) { - check(node); + checkHelperCall(node); super.MustacheStatement(node); } BlockStatement(node: hbs.AST.BlockStatement) { - check(node); + checkHelperCall(node); super.BlockStatement(node); } SubExpression(node: hbs.AST.SubExpression) { - check(node); + checkHelperCall(node); super.SubExpression(node); } + PartialStatement(node: hbs.AST.PartialStatement) { + partialRefs.push(node); + super.PartialStatement(node); + } + Decorator(node: hbs.AST.Decorator) { + found ??= toError(`Unknown decorator "${nameOf(node.path)}"`, node.path); + super.Decorator(node); + } + DecoratorBlock(node: hbs.AST.DecoratorBlock) { + const [partial] = node.params; + if (nameOf(node.path) === 'inline' && partial?.type === 'StringLiteral') { + inlinePartials.add(nameOf(partial)); + } else { + found ??= toError( + `Unknown decorator "${nameOf(node.path)}"`, + node.path, + ); + } + super.DecoratorBlock(node); + } } - new HelperCallVisitor().accept(Handlebars.parse(template)); - return found; + new Visitor().accept(Handlebars.parse(template)); + + // A partial block (`{{#> name}}…{{/name}}`) renders its fallback, so only a + // plain partial with no inline definition fails. + const unknownPartial = partialRefs.find( + ref => !inlinePartials.has(nameOf(ref.name)), + ); + return ( + found ?? + (unknownPartial == null + ? null + : toError( + `Unknown partial "${nameOf(unknownPartial.name)}"`, + unknownPartial.name, + )) + ); } /** * Rejects a body template that would fail on every alert delivery: one - * Handlebars cannot compile, or one that calls a helper delivery doesn't - * register. Slack never renders the body. + * Handlebars cannot compile, or one that uses a helper, partial, or decorator + * delivery doesn't provide. Slack never renders the body. */ function validateWebhookBodyTemplate({ service, @@ -250,7 +301,7 @@ function validateWebhookBodyTemplate({ if (service === WebhookService.Slack) return; const error = getWebhookTemplateError(body) ?? - (body?.trim() ? findUnknownHelperCall(body) : null); + (body?.trim() ? findUndeliverableConstruct(body) : null); if (error == null) return; const location = error.line == null From 9bc49f909899e689b443d204f1fe51ff38e1358b Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Wed, 14 Oct 2026 09:51:58 -0600 Subject: [PATCH 5/5] fix(api): allow @partial-block, move body template checks to their own module (greptile P1, P2) --- .../src/utils/__tests__/validators.test.ts | 21 ++- packages/api/src/utils/validators.ts | 151 +----------------- packages/api/src/utils/webhookBodyTemplate.ts | 151 ++++++++++++++++++ 3 files changed, 170 insertions(+), 153 deletions(-) create mode 100644 packages/api/src/utils/webhookBodyTemplate.ts diff --git a/packages/api/src/utils/__tests__/validators.test.ts b/packages/api/src/utils/__tests__/validators.test.ts index ac7842fd2e..fd9347006d 100644 --- a/packages/api/src/utils/__tests__/validators.test.ts +++ b/packages/api/src/utils/__tests__/validators.test.ts @@ -2,6 +2,10 @@ import { WebhookService } from '@hyperdx/common-utils/dist/types'; import { createHandlebarsWithHelpers } from '@/tasks/checkAlerts/transports'; import * as validators from '@/utils/validators'; +import { + WEBHOOK_BODY_HELPERS, + WebhookBodyValidationError, +} from '@/utils/webhookBodyTemplate'; describe('validators', () => { describe('isPrivateIp', () => { @@ -398,12 +402,19 @@ describe('validators', () => { ).toEqual([{ path: 'body', message: expect.stringContaining(message) }]); }); - it('accepts a partial block fallback and an inline partial', () => { + it.each([ + ['a partial block fallback', '{"a": "{{#> foo}}x{{/foo}}"}'], + ['an inline partial', '{"a": "{{#* inline "p"}}y{{/inline}}{{> p}}"}'], + [ + 'the built-in @partial-block', + '{{#*inline "layout"}}{{> @partial-block}}{{/inline}}{{#> layout}}{"a": 1}{{/layout}}', + ], + ])('accepts %s', (_label, body) => { expect( validators.getWebhookConfigErrors({ service: WebhookService.Generic, url: 'https://example.com/webhook', - body: '{"a": "{{#> foo}}x{{/foo}}", "b": "{{#* inline "p"}}y{{/inline}}{{> p}}"}', + body, }), ).toEqual([]); }); @@ -414,9 +425,7 @@ describe('validators', () => { ).filter( name => name !== 'helperMissing' && name !== 'blockHelperMissing', ); - expect([...validators.WEBHOOK_BODY_HELPERS].sort()).toEqual( - delivery.sort(), - ); + expect([...WEBHOOK_BODY_HELPERS].sort()).toEqual(delivery.sort()); }); it('accepts registered helpers and bare lookups', () => { @@ -460,7 +469,7 @@ describe('validators', () => { url: 'https://example.com/webhook', body: '{"text": "{{#if title}}"}', }), - ).toThrow(validators.WebhookBodyValidationError); + ).toThrow(WebhookBodyValidationError); }); }); diff --git a/packages/api/src/utils/validators.ts b/packages/api/src/utils/validators.ts index fb445a92b5..14e09f41c0 100644 --- a/packages/api/src/utils/validators.ts +++ b/packages/api/src/utils/validators.ts @@ -1,7 +1,3 @@ -import { - getWebhookTemplateError, - type WebhookTemplateError, -} from '@hyperdx/common-utils/dist/core/handlebarsEnv'; import { WebhookService } from '@hyperdx/common-utils/dist/types'; import { isValidSlackUrl, @@ -10,11 +6,14 @@ import { PASSWORD_SPECIAL_CHARS, passwordValidators, } from '@hyperdx/common-utils/dist/validation'; -import Handlebars from 'handlebars'; import { Address4, Address6 } from 'ip-address'; import { z } from 'zod'; import * as config from '@/config'; +import { + validateWebhookBodyTemplate, + WebhookBodyValidationError, +} from '@/utils/webhookBodyTemplate'; // Strips the surrounding brackets from IPv6 literals in URL hostnames (e.g. [::1] → ::1) export const IPV6_BRACKET_RE = /^\[|\]$/g; @@ -170,148 +169,6 @@ export function validateWebhookUrl( } } -export class WebhookBodyValidationError extends Error { - constructor(message: string) { - super(message); - this.name = 'WebhookBodyValidationError'; - } -} - -/** - * Helpers alert delivery registers (`createHandlebarsWithHelpers` in - * tasks/checkAlerts/transports/generic.ts). Listed here rather than imported - * because generic.ts imports this module; a unit test pins the two together. - */ -export const WEBHOOK_BODY_HELPERS = new Set([ - 'eq', - 'if', - 'unless', - 'each', - 'with', - 'lookup', - 'log', -]); - -type HelperCall = - | hbs.AST.MustacheStatement - | hbs.AST.BlockStatement - | hbs.AST.SubExpression; - -const toError = ( - message: string, - node: hbs.AST.Node, -): WebhookTemplateError => ({ - message, - line: node.loc.start.line, - column: node.loc.start.column + 1, -}); - -const nameOf = (node: hbs.AST.Expression): string => - 'original' in node ? String(node.original) : node.type; - -/** - * Finds the first construct that compiles but throws on every delivery: a - * call with arguments to a helper delivery doesn't register, a partial the - * template doesn't define inline, or a decorator other than `inline`. - * Handlebars only throws for these when they render, so a typo inside an - * untaken branch would pass a test render; walk the AST instead. - */ -function findUndeliverableConstruct( - template: string, -): WebhookTemplateError | null { - let found: WebhookTemplateError | null = null; - const inlinePartials = new Set(); - const partialRefs: hbs.AST.PartialStatement[] = []; - - const checkHelperCall = (node: HelperCall) => { - if (found != null || node.params.length === 0) return; - const { path } = node; - if ( - path.type === 'PathExpression' && - WEBHOOK_BODY_HELPERS.has(nameOf(path)) - ) - return; - found = toError(`Unknown helper "${nameOf(path)}"`, path); - }; - - class Visitor extends Handlebars.Visitor { - MustacheStatement(node: hbs.AST.MustacheStatement) { - checkHelperCall(node); - super.MustacheStatement(node); - } - BlockStatement(node: hbs.AST.BlockStatement) { - checkHelperCall(node); - super.BlockStatement(node); - } - SubExpression(node: hbs.AST.SubExpression) { - checkHelperCall(node); - super.SubExpression(node); - } - PartialStatement(node: hbs.AST.PartialStatement) { - partialRefs.push(node); - super.PartialStatement(node); - } - Decorator(node: hbs.AST.Decorator) { - found ??= toError(`Unknown decorator "${nameOf(node.path)}"`, node.path); - super.Decorator(node); - } - DecoratorBlock(node: hbs.AST.DecoratorBlock) { - const [partial] = node.params; - if (nameOf(node.path) === 'inline' && partial?.type === 'StringLiteral') { - inlinePartials.add(nameOf(partial)); - } else { - found ??= toError( - `Unknown decorator "${nameOf(node.path)}"`, - node.path, - ); - } - super.DecoratorBlock(node); - } - } - new Visitor().accept(Handlebars.parse(template)); - - // A partial block (`{{#> name}}…{{/name}}`) renders its fallback, so only a - // plain partial with no inline definition fails. - const unknownPartial = partialRefs.find( - ref => !inlinePartials.has(nameOf(ref.name)), - ); - return ( - found ?? - (unknownPartial == null - ? null - : toError( - `Unknown partial "${nameOf(unknownPartial.name)}"`, - unknownPartial.name, - )) - ); -} - -/** - * Rejects a body template that would fail on every alert delivery: one - * Handlebars cannot compile, or one that uses a helper, partial, or decorator - * delivery doesn't provide. Slack never renders the body. - */ -function validateWebhookBodyTemplate({ - service, - body, -}: { - service: WebhookService; - body?: string; -}) { - if (service === WebhookService.Slack) return; - const error = - getWebhookTemplateError(body) ?? - (body?.trim() ? findUndeliverableConstruct(body) : null); - if (error == null) return; - const location = - error.line == null - ? '' - : ` (line ${error.line}${error.column == null ? '' : `, column ${error.column}`})`; - throw new WebhookBodyValidationError( - `Invalid webhook body template${location}: ${error.message}`, - ); -} - /** A 400-worthy webhook config error whose message is safe to return. */ export const isWebhookValidationError = ( err: unknown, diff --git a/packages/api/src/utils/webhookBodyTemplate.ts b/packages/api/src/utils/webhookBodyTemplate.ts new file mode 100644 index 0000000000..881ecf465b --- /dev/null +++ b/packages/api/src/utils/webhookBodyTemplate.ts @@ -0,0 +1,151 @@ +import { + getWebhookTemplateError, + type WebhookTemplateError, +} from '@hyperdx/common-utils/dist/core/handlebarsEnv'; +import { WebhookService } from '@hyperdx/common-utils/dist/types'; +import Handlebars from 'handlebars'; + +export class WebhookBodyValidationError extends Error { + constructor(message: string) { + super(message); + this.name = 'WebhookBodyValidationError'; + } +} + +/** + * Helpers alert delivery registers (`createHandlebarsWithHelpers` in + * tasks/checkAlerts/transports/generic.ts). Listed here rather than imported, + * since generic.ts imports validators.ts, which imports this module. A unit + * test pins the two together. + */ +export const WEBHOOK_BODY_HELPERS = new Set([ + 'eq', + 'if', + 'unless', + 'each', + 'with', + 'lookup', + 'log', +]); + +type HelperCall = + | hbs.AST.MustacheStatement + | hbs.AST.BlockStatement + | hbs.AST.SubExpression; + +const toError = ( + message: string, + node: hbs.AST.Node, +): WebhookTemplateError => ({ + message, + line: node.loc.start.line, + column: node.loc.start.column + 1, +}); + +const nameOf = (node: hbs.AST.Expression): string => + 'original' in node ? String(node.original) : node.type; + +/** + * Finds the first construct that compiles but throws on every delivery: a + * call with arguments to a helper delivery doesn't register, a partial the + * template doesn't define inline, or a decorator other than `inline`. + * Handlebars only throws for these when they render, so a typo inside an + * untaken branch would pass a test render; walk the AST instead. + */ +function findUndeliverableConstruct( + template: string, +): WebhookTemplateError | null { + let found: WebhookTemplateError | null = null; + const inlinePartials = new Set(); + const partialRefs: hbs.AST.PartialStatement[] = []; + + const checkHelperCall = (node: HelperCall) => { + if (found != null || node.params.length === 0) return; + const { path } = node; + if ( + path.type === 'PathExpression' && + WEBHOOK_BODY_HELPERS.has(nameOf(path)) + ) + return; + found = toError(`Unknown helper "${nameOf(path)}"`, path); + }; + + class Visitor extends Handlebars.Visitor { + MustacheStatement(node: hbs.AST.MustacheStatement) { + checkHelperCall(node); + super.MustacheStatement(node); + } + BlockStatement(node: hbs.AST.BlockStatement) { + checkHelperCall(node); + super.BlockStatement(node); + } + SubExpression(node: hbs.AST.SubExpression) { + checkHelperCall(node); + super.SubExpression(node); + } + PartialStatement(node: hbs.AST.PartialStatement) { + partialRefs.push(node); + super.PartialStatement(node); + } + Decorator(node: hbs.AST.Decorator) { + found ??= toError(`Unknown decorator "${nameOf(node.path)}"`, node.path); + super.Decorator(node); + } + DecoratorBlock(node: hbs.AST.DecoratorBlock) { + const [partial] = node.params; + if (nameOf(node.path) === 'inline' && partial?.type === 'StringLiteral') { + inlinePartials.add(nameOf(partial)); + } else { + found ??= toError( + `Unknown decorator "${nameOf(node.path)}"`, + node.path, + ); + } + super.DecoratorBlock(node); + } + } + new Visitor().accept(Handlebars.parse(template)); + + // A partial block (`{{#> name}}…{{/name}}`) renders its fallback, so only a + // plain partial with no inline definition fails. + const unknownPartial = partialRefs.find(ref => { + const name = nameOf(ref.name); + // `@`-prefixed partials, like `@partial-block`, come from Handlebars. + return !name.startsWith('@') && !inlinePartials.has(name); + }); + return ( + found ?? + (unknownPartial == null + ? null + : toError( + `Unknown partial "${nameOf(unknownPartial.name)}"`, + unknownPartial.name, + )) + ); +} + +/** + * Rejects a body template that would fail on every alert delivery: one + * Handlebars cannot compile, or one that uses a helper, partial, or decorator + * delivery doesn't provide. Slack never renders the body. + */ +export function validateWebhookBodyTemplate({ + service, + body, +}: { + service: WebhookService; + body?: string; +}) { + if (service === WebhookService.Slack) return; + const error = + getWebhookTemplateError(body) ?? + (body?.trim() ? findUndeliverableConstruct(body) : null); + if (error == null) return; + const location = + error.line == null + ? '' + : ` (line ${error.line}${error.column == null ? '' : `, column ${error.column}`})`; + throw new WebhookBodyValidationError( + `Invalid webhook body template${location}: ${error.message}`, + ); +}