Merge pull request #28 from joaopcm/feat/discord-alert-channel

feat(alerts): add Discord as an official alert channel

Author: pontusab

README.md

@@ -395,11 +395,11 @@ Visit `http://localhost:PORT/jobs`.
 | `basePath` | `string`                            | Override base path detection. Required for `@getworkbench/elysia`, `@getworkbench/koa`, `@getworkbench/next`, `@getworkbench/tanstack-start`, `@getworkbench/astro`, `@getworkbench/nuxt`, and `@getworkbench/h3`. |
 | `readonly` | `boolean`                           | Disable actions (retry, remove, promote).                  |
 | `tags`     | `string[]`                          | Fields from `job.data` to extract as filterable tags.      |
-| `alerts`   | `AlertsOptions`                     | Self-hosted Slack/webhook alerting via BullMQ QueueEvents. |
+| `alerts`   | `AlertsOptions`                     | Self-hosted Slack/Discord/webhook alerting via BullMQ QueueEvents. |
 
 ### Alerts
 
-Alerts are on by default. Configure Slack or webhook **contact points** and **rules** in the dashboard **Alerts** page — notifications are only sent after you set that up. The model follows Grafana-style contact points + rules (unlike Bull Board, which has no built-in alerting). See [`@getworkbench/core` README](./packages/core/README.md) for Slack setup steps.
+Alerts are on by default. Configure Slack, Discord, or webhook **contact points** and **rules** in the dashboard **Alerts** page — notifications are only sent after you set that up. The model follows Grafana-style contact points + rules (unlike Bull Board, which has no built-in alerting). See [`@getworkbench/core` README](./packages/core/README.md) for setup steps.
 
 ## Packages
 

apps/web/content/docs/guides/alerts.mdx

@@ -1,17 +1,18 @@
 ---
 title: Alerts
-description: Self-hosted Slack and webhook alerting via BullMQ QueueEvents — contact points and rules in the dashboard.
+description: Self-hosted Slack, Discord, and webhook alerting via BullMQ QueueEvents — contact points and rules in the dashboard.
 keywords:
   - Workbench alerts
   - BullMQ Slack alerts
+  - BullMQ Discord alerts
 ---
 
 Alerts are **enabled by default**. Configure contact points and rules from the dashboard **Alerts** page — nothing is sent until you add destinations and matching rules.
 
 ## Configure in the dashboard
 
 1. Open your Workbench mount → **Alerts**
-2. **Add contact point** — Slack webhook or generic HTTP webhook
+2. **Add contact point** — Slack webhook, Discord webhook, or generic HTTP webhook
 3. **Add rule** — pick a trigger (job failed, stalled, retries exhausted, etc.) and link contact points
 
 ## Optional seed in code
@@ -73,6 +74,12 @@ Dashboard-managed config is **persisted in Redis** at `{prefix}:workbench:alerts
 
 Set `alerts.dashboardUrl` so notifications include an **Open in Workbench** link.
 
+## Discord setup
+
+1. Open your server → **Server Settings** → **Integrations** → **Webhooks**
+2. Click **New Webhook**, pick a channel, then **Copy Webhook URL** (`https://discord.com/api/webhooks/...`)
+3. In Workbench **Alerts** → **Add contact point** → preset **Discord** → paste URL → **Test**
+
 ## Comparison
 
 | Tool | Alert setup |

packages/core/README.md

@@ -118,7 +118,7 @@ Shared by every adapter and by `createFetchHandler` / `WorkbenchCore`:
 | `basePath` | `string` | Override base path detection. Required for some adapters (Elysia, Koa, Next.js, TanStack Start, Astro, Nuxt, h3, Adonis). |
 | `readonly` | `boolean` | Disable actions (retry, remove, promote). |
 | `tags` | `string[]` | Fields from `job.data` to extract as filterable tags. |
-| `alerts` | `AlertsOptions` | Self-hosted alerting via BullMQ `QueueEvents`, Slack/webhook contact points, and dashboard-managed rules. |
+| `alerts` | `AlertsOptions` | Self-hosted alerting via BullMQ `QueueEvents`, Slack/Discord/webhook contact points, and dashboard-managed rules. |
 
 ## Alerts
 

packages/core/src/core/alert-destinations.test.ts

@@ -1,6 +1,8 @@
 import { describe, expect, test } from "bun:test";
 import {
+  formatDiscordPayload,
   formatSlackPayload,
+  isDiscordWebhookUrl,
   isSlackIncomingWebhookUrl,
   validateContactPointUrl,
 } from "./alert-destinations";
@@ -16,6 +18,16 @@ const slackCp: AlertContactPoint = {
   updatedAt: 0,
 };
 
+const discordCp: AlertContactPoint = {
+  id: "cp-2",
+  name: "Discord #ops",
+  preset: "discord",
+  url: "https://discord.com/api/webhooks/123/abcDEF",
+  enabled: true,
+  createdAt: 0,
+  updatedAt: 0,
+};
+
 const sampleEvent: AlertEvent = {
   id: "evt-1",
   ruleId: "rule-1",
@@ -56,13 +68,48 @@ describe("isSlackIncomingWebhookUrl", () => {
   });
 });
 
+describe("isDiscordWebhookUrl", () => {
+  test("accepts standard Discord webhook URLs", () => {
+    expect(
+      isDiscordWebhookUrl("https://discord.com/api/webhooks/123/abcDEF"),
+    ).toBe(true);
+  });
+
+  test("accepts PTB Discord webhook URLs", () => {
+    expect(
+      isDiscordWebhookUrl("https://ptb.discord.com/api/webhooks/123/abcDEF"),
+    ).toBe(true);
+  });
+
+  test("rejects non-Discord URLs", () => {
+    expect(isDiscordWebhookUrl("https://example.com/api/webhooks/1/x")).toBe(
+      false,
+    );
+  });
+});
+
 describe("validateContactPointUrl", () => {
   test("requires Slack webhook host for slack preset", () => {
     expect(
       validateContactPointUrl("slack", "https://example.com/hook"),
     ).toContain("incoming webhook");
   });
 
+  test("requires Discord webhook host for discord preset", () => {
+    expect(
+      validateContactPointUrl("discord", "https://example.com/hook"),
+    ).toContain("discord.com");
+  });
+
+  test("accepts a valid Discord webhook URL", () => {
+    expect(
+      validateContactPointUrl(
+        "discord",
+        "https://discord.com/api/webhooks/123/abcDEF",
+      ),
+    ).toBeUndefined();
+  });
+
   test("allows generic https URLs for webhook preset", () => {
     expect(
       validateContactPointUrl("webhook", "https://example.com/hook"),
@@ -110,3 +157,39 @@ describe("formatSlackPayload", () => {
     expect(context?.elements).toBeDefined();
   });
 });
+
+describe("formatDiscordPayload", () => {
+  test("includes a colored embed and content fallback", () => {
+    const { url, headers, body } = formatDiscordPayload(discordCp, sampleEvent);
+
+    expect(url).toBe(discordCp.url);
+    expect(headers["Content-Type"]).toBe("application/json");
+
+    const payload = body as {
+      content: string;
+      embeds: Array<{ color: number; title: string }>;
+    };
+    expect(payload.content).toContain("Job failed");
+    expect(payload.embeds).toHaveLength(1);
+    expect(payload.embeds[0]?.color).toBe(0xf59e0b);
+    expect(payload.embeds[0]?.title).toContain("Job failed");
+  });
+
+  test("honors a custom sender name", () => {
+    const { body } = formatDiscordPayload(
+      { ...discordCp, displayName: "Ops Bot" },
+      sampleEvent,
+    );
+    expect((body as { username: string }).username).toBe("Ops Bot");
+  });
+
+  test("links to the dashboard for https URLs", () => {
+    const { body } = formatDiscordPayload(
+      discordCp,
+      sampleEvent,
+      "https://jobs.example.com/jobs",
+    );
+    const payload = body as { embeds: Array<{ description: string }> };
+    expect(payload.embeds[0]?.description).toContain("Open in Workbench");
+  });
+});

packages/core/src/core/alert-destinations.ts

@@ -22,6 +22,27 @@ export function isSlackIncomingWebhookUrl(url: string): boolean {
   }
 }
 
+const DISCORD_WEBHOOK_HOSTS = new Set([
+  "discord.com",
+  "discordapp.com",
+  "canary.discord.com",
+  "ptb.discord.com",
+]);
+
+/** Discord channel webhook URLs (https://discord.com/api/webhooks/:id/:token). */
+export function isDiscordWebhookUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    return (
+      parsed.protocol === "https:" &&
+      DISCORD_WEBHOOK_HOSTS.has(parsed.hostname) &&
+      parsed.pathname.startsWith("/api/webhooks/")
+    );
+  } catch {
+    return false;
+  }
+}
+
 export function validateContactPointUrl(
   preset: AlertContactPoint["preset"],
   url: string,
@@ -39,6 +60,10 @@ export function validateContactPointUrl(
     return "Slack contact points require an incoming webhook URL (https://hooks.slack.com/services/...)";
   }
 
+  if (preset === "discord" && !isDiscordWebhookUrl(url)) {
+    return "Discord contact points require a webhook URL (https://discord.com/api/webhooks/...)";
+  }
+
   return undefined;
 }
 
@@ -50,6 +75,16 @@ const SEVERITY_EMOJI: Record<string, string> = {
   info: "🔵",
 };
 
+const DISCORD_NEUTRAL_COLOR = 0x6b7280;
+
+const SEVERITY_COLOR: Record<string, number> = {
+  critical: 0xef4444,
+  warning: 0xf59e0b,
+  info: 0x3b82f6,
+};
+
+const DISCORD_FIELD_MAX = 1024;
+
 function severityLabel(severity: string): string {
   return severity.charAt(0).toUpperCase() + severity.slice(1);
 }
@@ -226,6 +261,79 @@ export function formatWebhookPayload(
   };
 }
 
+export function formatDiscordPayload(
+  contactPoint: AlertContactPoint,
+  event: AlertEvent,
+  dashboardUrl?: string,
+): FormattedDestinationPayload {
+  const emoji = SEVERITY_EMOJI[event.severity] ?? "⚪";
+  const link = buildDashboardLink(dashboardUrl, event);
+  const senderName = contactPoint.displayName ?? DEFAULT_ALERT_SENDER_NAME;
+  const iconUrl = contactPoint.iconUrl ?? DEFAULT_WORKBENCH_ICON_URL;
+
+  const fields: Array<{ name: string; value: string; inline?: boolean }> = [];
+  const pushField = (name: string, value: string, inline = true) => {
+    const trimmed = value.trim();
+    if (trimmed) {
+      fields.push({ name, value: trimmed.slice(0, DISCORD_FIELD_MAX), inline });
+    }
+  };
+
+  if (event.queue) {
+    pushField("Queue", event.queue);
+  }
+  if (event.jobName || event.jobId) {
+    pushField("Job", `${event.jobName ?? "—"} (\`${event.jobId ?? "—"}\`)`);
+  }
+  if (event.failedReason) {
+    pushField("Reason", event.failedReason.slice(0, 500), false);
+  }
+  if (event.counts) {
+    const parts: string[] = [];
+    if (event.counts.failed !== undefined) {
+      parts.push(`Failed: ${event.counts.failed}`);
+    }
+    if (event.counts.backlog !== undefined) {
+      parts.push(`Backlog: ${event.counts.backlog}`);
+    }
+    if (event.counts.workers !== undefined && event.counts.workers !== null) {
+      parts.push(`Workers: ${event.counts.workers}`);
+    }
+    pushField("Counts", parts.join(" · "));
+  }
+
+  let description = `**${severityLabel(event.severity)}** · \`${event.trigger}\`\n${event.message}`;
+  if (link?.startsWith("https://")) {
+    description += `\n\n**[Open in Workbench](${link})**`;
+  } else if (link) {
+    description += `\n\n${link}`;
+  }
+
+  const body = {
+    username: senderName,
+    avatar_url: iconUrl,
+    content: `${emoji} ${event.ruleName}: ${event.message}`,
+    embeds: [
+      {
+        title: `${emoji} ${event.ruleName}`,
+        description,
+        color: SEVERITY_COLOR[event.severity] ?? DISCORD_NEUTRAL_COLOR,
+        fields,
+        footer: {
+          text: event.status === "resolved" ? "✅ Resolved" : "🔔 Firing",
+        },
+        timestamp: new Date(event.firedAt).toISOString(),
+      },
+    ],
+  };
+
+  return {
+    url: contactPoint.url,
+    headers: { "Content-Type": "application/json" },
+    body,
+  };
+}
+
 export function formatDestinationPayload(
   contactPoint: AlertContactPoint,
   event: AlertEvent,
@@ -234,6 +342,9 @@ export function formatDestinationPayload(
   if (contactPoint.preset === "slack") {
     return formatSlackPayload(contactPoint, event, dashboardUrl);
   }
+  if (contactPoint.preset === "discord") {
+    return formatDiscordPayload(contactPoint, event, dashboardUrl);
+  }
   return formatWebhookPayload(contactPoint, event, dashboardUrl);
 }
 

packages/core/src/core/types.ts

@@ -66,9 +66,9 @@ export type AlertTrigger =
 
 export type AlertSeverity = "critical" | "warning" | "info";
 
-export type AlertContactPointPreset = "slack" | "webhook";
+export type AlertContactPointPreset = "slack" | "webhook" | "discord";
 
-/** Where notifications are sent (Slack incoming webhook or generic webhook) */
+/** Where notifications are sent (Slack/Discord incoming webhook or generic webhook) */
 export interface AlertContactPoint {
   id: string;
   name: string;