diff --git a/.changeset/webhook-tags-variable.md b/.changeset/webhook-tags-variable.md new file mode 100644 index 0000000000..4e21cb7661 --- /dev/null +++ b/.changeset/webhook-tags-variable.md @@ -0,0 +1,7 @@ +--- +'@hyperdx/common-utils': minor +'@hyperdx/api': minor +'@hyperdx/app': minor +--- + +feat: Expose alert tags to Generic and incident.io webhook bodies as `{{tags}}` (comma-separated, or iterate with `{{#each tags}}`), and include them in the default incident.io body's `metadata.tags`, so one shared webhook can route alerts by owning team diff --git a/docs/alert-webhook-template-variables.md b/docs/alert-webhook-template-variables.md index 2a78f461a6..83fb0ee7b2 100644 --- a/docs/alert-webhook-template-variables.md +++ b/docs/alert-webhook-template-variables.md @@ -25,6 +25,7 @@ a HyperDX alert without parsing the human-readable message body. | `{{sourceQuery}}` | string | The condition behind the alert — search expression or SQL (see below). | | `{{teamId}}` | string | Team the alert belongs to. | | `{{note}}` | string | The alert's freeform note — commonly a runbook link. | +| `{{tags}}` | list of strings | The alert's tags. `{{tags}}` renders them comma-separated (`team-payments,prod`); iterate with `{{#each tags}}` to emit a JSON array (see below). Empty when the alert has no tags. | Strings are JSON-escaped, so they are safe to drop into a quoted slot. Numbers (`startTime`, `endTime`, `threshold`, `thresholdMax`, `value`) are @@ -54,6 +55,16 @@ builder condition can each be Lucene or SQL, so the joined string is not necessarily valid in either. It is truncated at 2000 characters. PromQL charts do not support alerts, so no webhook carries a PromQL expression. +Tags let one shared webhook route alerts by owner: tag each alert with its +team and read the tag in the receiver. To send them as a JSON array rather +than one comma-separated string: + +``` +{ + "tags": [{{#each tags}}"{{this}}"{{#unless @last}}, {{/unless}}{{/each}}] +} +``` + An empty string is not valid JSON in an unquoted numeric slot, so guard any number that may be absent. Compare against `undefined` rather than using `{{#if}}`, which treats a legitimate bound of `0` as absent: @@ -86,8 +97,8 @@ which is what the guard above is for. incident.io accepts only `firing` or `resolved` in `status`, so the default body maps HyperDX's state onto those two and carries `{{status}}` in -`metadata.hyperdx_status`, alongside the alert id, condition and evaluation -window. Only a firing and a resolve are delivered today, so that key reads +`metadata.hyperdx_status`, alongside the alert id, condition, evaluation +window and the alert's tags (comma-separated, in `metadata.tags`). Only a firing and a resolve are delivered today, so that key reads `firing` or `resolved` as well. `metadata` is free-form, but incident.io only surfaces the keys its alert source is configured to parse. diff --git a/packages/api/src/routers/api/webhooks.ts b/packages/api/src/routers/api/webhooks.ts index 4973dff1d8..516cb283a2 100644 --- a/packages/api/src/routers/api/webhooks.ts +++ b/packages/api/src/routers/api/webhooks.ts @@ -495,6 +495,7 @@ router.post( sourceQuery: 'SeverityText: "error"', teamId: teamId.toString(), note: 'Test webhook — no runbook', + tags: ['test-tag'], }; const testChannel = { type: 'webhook' as const, channel: testWebhook }; diff --git a/packages/api/src/tasks/checkAlerts/template.ts b/packages/api/src/tasks/checkAlerts/template.ts index 5cb3b148b3..11335c5a1d 100644 --- a/packages/api/src/tasks/checkAlerts/template.ts +++ b/packages/api/src/tasks/checkAlerts/template.ts @@ -766,6 +766,7 @@ export const renderAlertTemplate = async ({ ), teamId, note: alert.note ?? '', + tags: alert.tags ?? [], }, }); return true; diff --git a/packages/api/src/tasks/checkAlerts/transports/__tests__/generic.test.ts b/packages/api/src/tasks/checkAlerts/transports/__tests__/generic.test.ts index 1f99435526..d23912e4d4 100644 --- a/packages/api/src/tasks/checkAlerts/transports/__tests__/generic.test.ts +++ b/packages/api/src/tasks/checkAlerts/transports/__tests__/generic.test.ts @@ -144,11 +144,33 @@ describe('buildWebhookTemplateVariables', () => { expect(buildWebhookTemplateVariables(message).var).toEqual({}); }); + it('exposes tags as a comma-joined string and as a JSON-escaped list', () => { + const vars = buildWebhookTemplateVariables({ + ...message, + tags: ['team-payments', 'say "hi"'], + }); + const render = (template: string) => + JSON.parse( + createHandlebarsWithHelpers().compile(template, { noEscape: true })( + vars, + ), + ); + + expect(render('{"tags": "{{tags}}"}').tags).toBe('team-payments,say "hi"'); + // The array form published in docs/alert-webhook-template-variables.md. + expect( + render( + '{"tags": [{{#each tags}}"{{this}}"{{#unless @last}}, {{/unless}}{{/each}}]}', + ).tags, + ).toEqual(['team-payments', 'say "hi"']); + }); + it('renders enriched fields as empty strings (never "undefined") when absent', () => { const vars = buildWebhookTemplateVariables(message); expect(vars.alertId).toBe(''); expect(vars.status).toBe(''); expect(vars.note).toBe(''); + expect(vars.tags).toEqual([]); expect(vars.startTimeISO).toBe(new Date(0).toISOString()); // A raw number renders as an empty slot when absent, not "undefined". expect(vars.thresholdMax).toBeUndefined(); @@ -220,6 +242,9 @@ describe('the default incident.io body', () => { value: '42', group_key: 'checkout', }); + expect(render({ tags: ['team-payments', 'prod'] }).metadata.tags).toBe( + 'team-payments,prod', + ); }); it('stays valid JSON when the alert carries no optional values', () => { @@ -237,6 +262,7 @@ describe('the default incident.io body', () => { hyperdx_status: 'no_data', threshold_max: '', value: '', + tags: '', }); }); }); diff --git a/packages/api/src/tasks/checkAlerts/transports/generic.ts b/packages/api/src/tasks/checkAlerts/transports/generic.ts index 2dd60b983c..035ff547f0 100644 --- a/packages/api/src/tasks/checkAlerts/transports/generic.ts +++ b/packages/api/src/tasks/checkAlerts/transports/generic.ts @@ -101,13 +101,15 @@ export const buildWebhookTemplateVariables = (message: Message) => note: escapeJsonString(message.note ?? ''), sourceQuery: escapeJsonString(message.sourceQuery ?? ''), status: escapeJsonString(message.status ?? ''), + // An array so `{{tags}}` renders comma-joined and `{{#each tags}}` works. + tags: (message.tags ?? []).map(escapeJsonString), teamId: escapeJsonString(message.teamId ?? ''), threshold: message.threshold, thresholdMax: message.thresholdMax, value: message.value, }) satisfies Record< WebhookTemplateVariable, - string | number | undefined | Record + string | number | undefined | string[] | Record >; /** diff --git a/packages/api/src/tasks/checkAlerts/transports/types.ts b/packages/api/src/tasks/checkAlerts/transports/types.ts index 7ed52698cd..ddae002898 100644 --- a/packages/api/src/tasks/checkAlerts/transports/types.ts +++ b/packages/api/src/tasks/checkAlerts/transports/types.ts @@ -28,6 +28,7 @@ export interface Message { sourceQuery?: string; // the search expr / SQL that defines the alert teamId?: string; note?: string; // freeform alert note (markdown); commonly holds a runbook link + tags?: string[]; } export type WebhookChannel = Extract< diff --git a/packages/app/src/components/TeamSettings/WebhookForm.tsx b/packages/app/src/components/TeamSettings/WebhookForm.tsx index 4aac573677..6cf1720e5d 100644 --- a/packages/app/src/components/TeamSettings/WebhookForm.tsx +++ b/packages/app/src/components/TeamSettings/WebhookForm.tsx @@ -66,6 +66,7 @@ const describeTemplateVariable = ( endTimeISO: 'Window end, ISO-8601', teamId: 'Team the alert belongs to', note: "Alert's note, commonly a runbook link", + tags: "Alert's tags, comma-separated; iterate with {{#each tags}}", }); export const getWebhookTemplateVariables = ( diff --git a/packages/common-utils/src/types.ts b/packages/common-utils/src/types.ts index f1c006a299..b8c3bc1525 100644 --- a/packages/common-utils/src/types.ts +++ b/packages/common-utils/src/types.ts @@ -652,6 +652,7 @@ export const WEBHOOK_TEMPLATE_VARIABLES = [ 'sourceQuery', 'teamId', 'note', + 'tags', ] as const; export type WebhookTemplateVariable = @@ -778,7 +779,8 @@ export const DEFAULT_INCIDENT_IO_WEBHOOK_BODY = `{ "value": "{{value}}", "group_key": "{{groupKey}}", "window_start": "{{startTimeISO}}", - "window_end": "{{endTimeISO}}" + "window_end": "{{endTimeISO}}", + "tags": "{{tags}}" } }`;