diff --git a/.changeset/webhook-body-template-api-validation.md b/.changeset/webhook-body-template-api-validation.md new file mode 100644 index 0000000000..11880a9d8e --- /dev/null +++ b/.changeset/webhook-body-template-api-validation.md @@ -0,0 +1,9 @@ +--- +'@hyperdx/api': patch +--- + +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 05d1a37539..7443a8ea57 100644 --- a/docs/alert-webhook-template-variables.md +++ b/docs/alert-webhook-template-variables.md @@ -71,7 +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. +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 1ac293d77f..30ff03cf14 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 or calls a helper other than `eq` and the Handlebars built-ins.", "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, without the write-only\n`headers` and `queryParams`. Populated when valid is\ntrue, null 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..a37f41fcbe 100644 --- a/packages/api/src/controllers/webhook.ts +++ b/packages/api/src/controllers/webhook.ts @@ -4,7 +4,7 @@ import Webhook, { type WebhookDocument, WebhookService, } from '@/models/webhook'; -import { validateWebhookUrl } from '@/utils/validators'; +import { validateWebhookConfig } from '@/utils/validators'; export interface WebhookInput { name: string; @@ -24,7 +24,7 @@ export async function createWebhook( team: ObjectId | string, { name, service, url, description, queryParams, headers, body }: WebhookInput, ) { - validateWebhookUrl({ service, url }); + validateWebhookConfig({ service, url, body }); return Webhook.create({ team, @@ -60,7 +60,7 @@ export async function updateWebhook( return { status: 'not_found' }; } - validateWebhookUrl({ service, url }); + validateWebhookConfig({ service, url, 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..e8e33590f7 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,12 @@ 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 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.', ), }); @@ -138,7 +142,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..55520e121f 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,127 @@ 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 / - 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); + + 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..db9bdb80b7 100644 --- a/packages/api/src/routers/api/webhooks.ts +++ b/packages/api/src/routers/api/webhooks.ts @@ -28,8 +28,8 @@ import { import type { Message } from '@/tasks/checkAlerts/transports/types'; import { isDuplicateKeyError } from '@/utils/errors'; import { - validateWebhookUrl, - WebhookUrlValidationError, + isWebhookValidationError, + validateWebhookConfig, } from '@/utils/validators'; import { webhookHeaderNameSchema, @@ -122,11 +122,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 +211,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)) { @@ -289,7 +289,7 @@ router.put( }); } - validateWebhookUrl({ service, url: resolvedUrl }); + 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 @@ -361,7 +361,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)) { @@ -455,7 +455,7 @@ router.post( } } - validateWebhookUrl({ service, url }); + validateWebhookConfig({ service, url, body }); // Create a temporary webhook object for testing const testWebhook = new Webhook({ @@ -515,7 +515,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..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 @@ -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,100 @@ 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, minus write-only secrets', async () => { + const response = await authRequest('post', VALIDATE_URL) + .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: { ...readable, 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 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({ + ...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..479334e13e 100644 --- a/packages/api/src/routers/external-api/v2/webhooks.ts +++ b/packages/api/src/routers/external-api/v2/webhooks.ts @@ -17,7 +17,10 @@ import { paginationMeta, paginationQuerySchema, } from '@/utils/pagination'; -import { WebhookUrlValidationError } from '@/utils/validators'; +import { + getWebhookConfigErrors, + isWebhookValidationError, +} from '@/utils/validators'; import { ExternalWebhook, externalWebhookCreateSchema, @@ -28,11 +31,11 @@ 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; }; @@ -407,7 +410,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 or calls a helper other than `eq` and the Handlebars built-ins. * example: '{"alert": "{{title}}", "severity": "{{level}}"}' * headers: * type: object @@ -433,6 +436,131 @@ 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, without the write-only + * `headers` and `queryParams`. 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 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 ? readable : null, + }); + } catch (e) { + next(e); + } +}); + /** * @openapi * /api/v2/webhooks: @@ -503,7 +631,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 +751,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/__tests__/validators.test.ts b/packages/api/src/utils/__tests__/validators.test.ts index f9f42d1387..fd9347006d 100644 --- a/packages/api/src/utils/__tests__/validators.test.ts +++ b/packages/api/src/utils/__tests__/validators.test.ts @@ -1,6 +1,11 @@ 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', () => { @@ -317,6 +322,157 @@ 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 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.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.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, + }), + ).toEqual([]); + }); + + it('knows exactly the helpers delivery registers', () => { + const delivery = Object.keys( + createHandlebarsWithHelpers().helpers, + ).filter( + name => name !== 'helperMissing' && name !== 'blockHelperMissing', + ); + expect([...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', + 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(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 0cc6fe169b..14e09f41c0 100644 --- a/packages/api/src/utils/validators.ts +++ b/packages/api/src/utils/validators.ts @@ -10,6 +10,10 @@ 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; @@ -165,6 +169,45 @@ export function validateWebhookUrl( } } +/** 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; + +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( 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}`, + ); +}