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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .changeset/webhook-body-template-api-validation.md
Original file line number Diff line number Diff line change
@@ -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.
4 changes: 3 additions & 1 deletion docs/alert-webhook-template-variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
122 changes: 121 additions & 1 deletion packages/api/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand Down Expand Up @@ -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",
Expand Down
6 changes: 3 additions & 3 deletions packages/api/src/controllers/webhook.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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,
Expand Down Expand Up @@ -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;
Expand Down
43 changes: 43 additions & 0 deletions packages/api/src/mcp/__tests__/webhooks.int.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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();

Expand Down
12 changes: 8 additions & 4 deletions packages/api/src/mcp/tools/alerts/saveWebhook.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.',
),
});

Expand Down Expand Up @@ -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)) {
Expand Down
Loading
Loading