Skip to content
Merged
7 changes: 7 additions & 0 deletions .changeset/alert-title-emoji-toggle.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@hyperdx/api': minor
'@hyperdx/app': minor
'@hyperdx/common-utils': minor
---

feat: add optional `titleEmoji` webhook option; `false` removes the emoji prefix from notification titles sent through that webhook
24 changes: 22 additions & 2 deletions packages/api/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -5827,6 +5827,11 @@
"description": "Webhook description, shown in the UI",
"example": "Sends critical alerts to the #incidents channel"
},
"titleEmoji": {
"type": "boolean",
"description": "Set to false to omit the state emoji prefix from notification titles sent through this webhook. Unset or true keeps the default prefix.",
"example": false
},
"updatedAt": {
"type": "string",
"format": "date-time",
Expand Down Expand Up @@ -5879,6 +5884,11 @@
"description": "Webhook description, shown in the UI",
"example": "Routes alerts to incident.io for on-call escalation"
},
"titleEmoji": {
"type": "boolean",
"description": "Set to false to omit the state emoji prefix from notification titles sent through this webhook. Unset or true keeps the default prefix.",
"example": false
},
"updatedAt": {
"type": "string",
"format": "date-time",
Expand Down Expand Up @@ -5931,6 +5941,11 @@
"description": "Webhook description, shown in the UI",
"example": "Forwards alert payloads to an external monitoring service"
},
"titleEmoji": {
"type": "boolean",
"description": "Set to false to omit the state emoji prefix from notification titles sent through this webhook. Unset or true keeps the default prefix.",
"example": false
},
"body": {
"type": "string",
"description": "Optional request body template",
Expand Down Expand Up @@ -6023,7 +6038,7 @@
"service",
"url"
],
"description": "Webhook create/update body. `body`, `headers`, and `queryParams`\nonly take effect for services that issue a templated HTTP request\n(`generic`, `incidentio`). The `slack` service posts a fixed payload\nto its incoming-webhook URL and ignores them, so supplying any of\nthese fields on a `slack` webhook is rejected. `headers` and\n`queryParams` are write-only — they are accepted here but never\nreturned by any read endpoint, so secrets such as auth tokens do\nnot leak. On\nupdate (PUT), omitted readable fields (`description`, `body`) are\ncleared, while omitted `headers`/`queryParams` are preserved —\nsend an explicit `{}` to clear them. Exception: if the destination\n(`url` or `service`) changes, omitted `headers`/`queryParams` are\ncleared rather than preserved, so stored secrets are never forwarded\nto a new destination; re-supply them for the new destination.\n",
"description": "Webhook create/update body. `body`, `headers`, and `queryParams`\nonly take effect for services that issue a templated HTTP request\n(`generic`, `incidentio`). The `slack` service posts a fixed payload\nto its incoming-webhook URL and ignores them, so supplying any of\nthese fields on a `slack` webhook is rejected. `headers` and\n`queryParams` are write-only — they are accepted here but never\nreturned by any read endpoint, so secrets such as auth tokens do\nnot leak. On\nupdate (PUT), omitted readable fields (`description`, `titleEmoji`, `body`) are\ncleared, while omitted `headers`/`queryParams` are preserved —\nsend an explicit `{}` to clear them. Exception: if the destination\n(`url` or `service`) changes, omitted `headers`/`queryParams` are\ncleared rather than preserved, so stored secrets are never forwarded\nto a new destination; re-supply them for the new destination.\n",
"properties": {
"name": {
"type": "string",
Expand Down Expand Up @@ -6054,6 +6069,11 @@
"description": "Webhook description, shown in the UI.",
"example": "Sends critical alerts to the #incidents channel"
},
"titleEmoji": {
"type": "boolean",
"description": "Set to false to omit the state emoji prefix from notification titles sent through this webhook. Unset or true keeps the default prefix.",
"example": false
},
"body": {
"type": "string",
"maxLength": 16384,
Expand Down Expand Up @@ -9178,7 +9198,7 @@
"/api/v2/webhooks/{id}": {
"put": {
"summary": "Update Webhook",
"description": "Replaces an existing webhook. Readable optional fields\n(`description`, `body`) are a full replace: omitting them clears\nthem. The write-only fields `headers` and `queryParams` are never\nreturned on read, so omitting them preserves the stored values;\nsend an explicit empty object (`{}`) to clear them. Exception: if the\ndestination (`url` or `service`) changes, omitted `headers`/\n`queryParams` are cleared rather than preserved so stored secrets are\nnever forwarded to a new destination.\n",
"description": "Replaces an existing webhook. Readable optional fields\n(`description`, `titleEmoji`, `body`) are a full replace: omitting them clears\nthem. The write-only fields `headers` and `queryParams` are never\nreturned on read, so omitting them preserves the stored values;\nsend an explicit empty object (`{}`) to clear them. Exception: if the\ndestination (`url` or `service`) changes, omitted `headers`/\n`queryParams` are cleared rather than preserved so stored secrets are\nnever forwarded to a new destination.\n",
"operationId": "updateWebhook",
"tags": [
"Webhooks"
Expand Down
27 changes: 25 additions & 2 deletions packages/api/src/controllers/webhook.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ export interface WebhookInput {
service: WebhookService;
url: string;
description?: string;
titleEmoji?: boolean;
queryParams?: Record<string, string>;
headers?: Record<string, string>;
body?: string;
Expand All @@ -22,7 +23,16 @@ export interface WebhookInput {
*/
export async function createWebhook(
team: ObjectId | string,
{ name, service, url, description, queryParams, headers, body }: WebhookInput,
{
name,
service,
url,
description,
titleEmoji,
queryParams,
headers,
body,
}: WebhookInput,
) {
validateWebhookConfig({ service, url, body });

Expand All @@ -32,6 +42,7 @@ export async function createWebhook(
service,
url,
description,
titleEmoji,
queryParams,
headers,
body,
Expand All @@ -53,7 +64,16 @@ export type UpdateWebhookResult =
export async function updateWebhook(
team: ObjectId | string,
webhookId: string,
{ name, service, url, description, queryParams, headers, body }: WebhookInput,
{
name,
service,
url,
description,
titleEmoji,
queryParams,
headers,
body,
}: WebhookInput,
): Promise<UpdateWebhookResult> {
const existing = await Webhook.findOne({ _id: webhookId, team });
if (existing == null) {
Expand All @@ -71,6 +91,9 @@ export async function updateWebhook(
if (description === undefined) unsetFields.description = 1;
else setFields.description = description;

if (titleEmoji === undefined) unsetFields.titleEmoji = 1;
else setFields.titleEmoji = titleEmoji;

if (body === undefined) unsetFields.body = 1;
else setFields.body = body;

Expand Down
12 changes: 10 additions & 2 deletions packages/api/src/mcp/tools/alerts/saveWebhook.ts
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,14 @@ const mcpSaveWebhookSchema = z.object({
'Description shown in the UI. On update this is a full replace: ' +
'omitting it clears the stored description.',
),
titleEmoji: z
.boolean()
.optional()
.describe(
'Set to false to omit the state emoji prefix from notification titles ' +
'sent through this webhook. On update this is a full replace: ' +
'omitting it restores the default prefix.',
),
headers: z
.record(z.string(), z.string())
.optional()
Expand Down Expand Up @@ -105,8 +113,8 @@ export function registerSaveWebhook({
'clickstack_save_alert. For the slack service the url host must end ' +
'in slack.com and headers/queryParams/body are not supported. On ' +
'update, every alert using this webhook sends its next notifications ' +
'with the new settings, including a changed url. description and body ' +
'are a full replace (omitting them clears them), while write-only ' +
'with the new settings, including a changed url. description, titleEmoji and ' +
'body are a full replace (omitting them clears them), while write-only ' +
'headers/queryParams are preserved when omitted (send {} to clear); ' +
'changing url or service clears omitted headers/queryParams. ' +
'url, headers, and queryParams are never returned.',
Expand Down
6 changes: 6 additions & 0 deletions packages/api/src/models/webhook.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@ export interface IWebhook {
updatedAt: Date;
url?: string;
description?: string;
// false drops the state emoji prefix from notification titles
titleEmoji?: boolean;
// reminder to serialize/convert the Mongoose model instance to a plain javascript object when using
// to strip the additional properties that are related to the Mongoose internal representation -> webhook.headers.toJSON()
queryParams?: MongooseMap;
Expand Down Expand Up @@ -50,6 +52,10 @@ const WebhookSchema = new Schema<IWebhook>(
type: String,
required: false,
},
titleEmoji: {
type: Boolean,
required: false,
},
queryParams: {
type: Map,
of: String,
Expand Down
57 changes: 57 additions & 0 deletions packages/api/src/routers/api/__tests__/webhooks.int.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,44 @@ describe('webhooks router', () => {
expect(webhooks[0].url).toBe(MOCK_WEBHOOK.url);
});

it('POST / - stores titleEmoji false and GET / returns it', async () => {
const { agent } = await getLoggedInAgent(server);

const response = await agent
.post('/webhooks')
.send({ ...MOCK_WEBHOOK, titleEmoji: false })
.expect(200);

expect(response.body.data.titleEmoji).toBe(false);

const webhooks = await Webhook.find({});
expect(webhooks).toHaveLength(1);
expect(webhooks[0].titleEmoji).toBe(false);

const listResponse = await agent
.get('/webhooks')
.query({ service: WebhookService.Slack })
.expect(200);

expect(listResponse.body.data).toHaveLength(1);
expect(listResponse.body.data[0].titleEmoji).toBe(false);
});

it('POST / - leaves titleEmoji unset when not provided', async () => {
const { agent } = await getLoggedInAgent(server);

const response = await agent
.post('/webhooks')
.send(MOCK_WEBHOOK)
.expect(200);

expect(response.body.data).not.toHaveProperty('titleEmoji');

const webhooks = await Webhook.find({});
expect(webhooks).toHaveLength(1);
expect(webhooks[0].titleEmoji).toBeUndefined();
});

it('POST / - returns 400 when webhook with same URL already exists', async () => {
const { agent, team } = await getLoggedInAgent(server);

Expand Down Expand Up @@ -787,6 +825,25 @@ describe('webhooks router', () => {
});
});

it('sets titleEmoji on an existing webhook', async () => {
const { agent, team } = await getLoggedInAgent(server);

const webhook = await Webhook.create({
...MOCK_WEBHOOK,
team: team._id,
});

const response = await agent
.put(`/webhooks/${webhook._id}`)
.send({ ...MOCK_WEBHOOK, titleEmoji: false })
.expect(200);

expect(response.body.data.titleEmoji).toBe(false);

const updatedWebhook = await Webhook.findById(webhook._id);
expect(updatedWebhook?.titleEmoji).toBe(false);
});

it('returns 404 when webhook does not exist', async () => {
const { agent } = await getLoggedInAgent(server);

Expand Down
28 changes: 24 additions & 4 deletions packages/api/src/routers/api/webhooks.ts
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,7 @@ router.post(
body: z.object({
body: z.string().optional(),
description: z.string().optional(),
titleEmoji: z.boolean().optional(),
headers: z
.record(webhookHeaderNameSchema, webhookHeaderValueSchema)
.optional(),
Expand All @@ -188,8 +189,16 @@ router.post(
if (teamId == null) {
return res.sendStatus(403);
}
const { name, service, url, description, queryParams, headers, body } =
req.body;
const {
name,
service,
url,
description,
titleEmoji,
queryParams,
headers,
body,
} = req.body;
// The unique index is on (team, service, name), so the pre-flight check
// must query the same fields — otherwise a name+service collision slips
// past this guard and surfaces as an uncaught duplicate-key 500 below.
Expand All @@ -203,6 +212,7 @@ router.post(
service,
url,
description,
titleEmoji,
queryParams,
headers,
body,
Expand Down Expand Up @@ -233,6 +243,7 @@ router.put(
body: z.object({
body: z.string().optional(),
description: z.string().optional(),
titleEmoji: z.boolean().optional(),
headers: z
.record(webhookHeaderNameSchema, webhookHeaderValueSchema)
.optional(),
Expand All @@ -254,8 +265,16 @@ router.put(
if (teamId == null) {
return res.sendStatus(403);
}
const { name, service, url, description, queryParams, headers, body } =
req.body;
const {
name,
service,
url,
description,
titleEmoji,
queryParams,
headers,
body,
} = req.body;
const { id } = req.params;

const existingWebhook = await Webhook.findOne({
Expand Down Expand Up @@ -323,6 +342,7 @@ router.put(
service,
url: resolvedUrl,
description,
titleEmoji,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — The internal webhook API that the UI uses has no tests for titleEmoji

The new tests cover only the v2 external API (external-api/__tests__/webhooks.int.test.ts). The Team Settings form goes through routers/api/webhooks.ts, which saves titleEmoji with its own $set code and has no test. Add create, update and list cases in packages/api/src/routers/api/__tests__/webhooks.int.test.ts checking that titleEmoji: false is stored and returned, and what happens when it is omitted.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added in fd50389: create with and without titleEmoji, update, and list through the internal router.

body,
};
const $unset: Record<string, 1> = {};
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -331,6 +331,27 @@ describe('External API v2 Webhooks', () => {
.expect(401);
});

it('should round-trip titleEmoji through create and list', async () => {
const response = await authRequest('post', WEBHOOKS_BASE_URL)
.send({ ...MOCK_SLACK_WEBHOOK, titleEmoji: false })
.expect(200);
expect(response.body.data.titleEmoji).toBe(false);

const stored = await Webhook.findById(response.body.data.id).lean();
expect(stored?.titleEmoji).toBe(false);

const list = await authRequest('get', WEBHOOKS_BASE_URL).expect(200);
expect(list.body.data[0].titleEmoji).toBe(false);
});

it('should leave titleEmoji unset when not provided', async () => {
const response = await authRequest('post', WEBHOOKS_BASE_URL)
.send(MOCK_SLACK_WEBHOOK)
.expect(200);

expect(response.body.data).not.toHaveProperty('titleEmoji');
});

it('should create a Slack webhook and never return sensitive fields', async () => {
const response = await authRequest('post', WEBHOOKS_BASE_URL)
.send(MOCK_GENERIC_WEBHOOK)
Expand Down Expand Up @@ -635,6 +656,36 @@ describe('External API v2 Webhooks', () => {
expect(stored?.description).toBeUndefined();
});

it('should set titleEmoji on update and clear it when omitted', async () => {
const created = await Webhook.create({
...MOCK_SLACK_WEBHOOK,
team: team._id,
});
const base = {
name: MOCK_SLACK_WEBHOOK.name,
service: WebhookService.Slack,
url: MOCK_SLACK_WEBHOOK.url,
};

const set = await authRequest(
'put',
`${WEBHOOKS_BASE_URL}/${created._id}`,
)
.send({ ...base, titleEmoji: false })
.expect(200);
expect(set.body.data.titleEmoji).toBe(false);
expect((await Webhook.findById(created._id).lean())?.titleEmoji).toBe(
false,
);

await authRequest('put', `${WEBHOOKS_BASE_URL}/${created._id}`)
.send(base)
.expect(200);
expect(
(await Webhook.findById(created._id).lean())?.titleEmoji,
).toBeUndefined();
});

it('should preserve omitted queryParams when the destination is unchanged', async () => {
const created = await Webhook.create({
...MOCK_GENERIC_WEBHOOK,
Expand Down
Loading
Loading