feat: add optional titleEmoji webhook setting to drop the emoji prefix (#3467)

## Summary

Closes #3466

I know #3466 hasn't been through feedback yet and CONTRIBUTING asks for `Accepting PR` first. I had already written and tested this before filing the issue, so I'm opening it now in case it helps the discussion. Happy to rework it or close it if you want a different direction.

Alert notification titles always start with 🚨 or ✅. That reads well in Slack, but a destination that already says firing or resolved, such as a webhook feeding an email relay, gets the emoji in its subject line with no way to remove it.

Following review, this is now a setting on the webhook rather than the alert: an optional boolean `titleEmoji`, where `false` drops the prefix for notifications sent to that webhook. Unset or `true` leaves titles unchanged. An alert that notifies several webhooks through `@webhook-` mentions gets the prefix per destination.

- The title is built once without the emoji, and the prefix is added per channel when the dispatch jobs are queued, unless that webhook opts out.
- The field follows `description` through the webhook model, the internal and v2 webhook APIs, `openapi.json` and the common-utils types.
- The webhook form has a "Show state emoji in notification titles" checkbox, checked by default.
- The MCP `saveWebhook` tool takes the field, since its update clears omitted settings.

### How to reproduce

**Starting point:** `yarn dev`, with two webhook destinations and a saved-search alert that notifies both (one as its channel, one through an `@webhook-` mention in the message).

**On `main`:**

1. Trigger the alert. Both notification titles start with 🚨, and no setting removes it.

**On this branch:**

1. In Team Settings, edit the first webhook and untick "Show state emoji in notification titles".
2. Trigger the alert. The first webhook's title has no prefix, the second keeps 🚨, and the resolved notifications follow the same split.
3. `GET /api/v2/webhooks` returns `"titleEmoji": false` for the first webhook.

`make dev-int FILE=checkAlerts` runs the two-webhook case.

### How to test on Vercel preview

Open Team Settings, edit or create a webhook, and check that the new checkbox saves and reloads.

### References

- Linear Issue:
- Related PRs: #1339

Author: andrewdunndev

.changeset/alert-title-emoji-toggle.md

@@ -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

packages/api/openapi.json

@@ -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",
@@ -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",
@@ -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",
@@ -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",
@@ -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,
@@ -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"

packages/api/src/controllers/webhook.ts

@@ -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;
@@ -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 });
 
@@ -32,6 +42,7 @@ export async function createWebhook(
     service,
     url,
     description,
+    titleEmoji,
     queryParams,
     headers,
     body,
@@ -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) {
@@ -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;
 

packages/api/src/mcp/tools/alerts/saveWebhook.ts

@@ -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()
@@ -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.',

packages/api/src/models/webhook.ts

@@ -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;
@@ -50,6 +52,10 @@ const WebhookSchema = new Schema<IWebhook>(
       type: String,
       required: false,
     },
+    titleEmoji: {
+      type: Boolean,
+      required: false,
+    },
     queryParams: {
       type: Map,
       of: String,

packages/api/src/routers/api/__tests__/webhooks.int.test.ts

@@ -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);
 
@@ -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);
 

packages/api/src/routers/api/webhooks.ts

@@ -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(),
@@ -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.
@@ -203,6 +212,7 @@ router.post(
         service,
         url,
         description,
+        titleEmoji,
         queryParams,
         headers,
         body,
@@ -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(),
@@ -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({
@@ -323,6 +342,7 @@ router.put(
         service,
         url: resolvedUrl,
         description,
+        titleEmoji,
         body,
       };
       const $unset: Record<string, 1> = {};

packages/api/src/routers/external-api/__tests__/webhooks.int.test.ts

@@ -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)
@@ -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,