feat: add webhook notifications for high-vote feedback items

When a feedback item's vote count crosses a configurable threshold, a POST
is sent to one or more webhook URLs. Both Slack incoming webhooks and Discord
webhooks are supported (payload includes both `text` and `content` keys).

Configuration in `.suggestion-box/config.json`:

  {
    "webhooks": [
      { "url": "https://hooks.slack.com/services/...", "voteThreshold": 3 },
      { "url": "https://discord.com/api/webhooks/...", "voteThreshold": 5 }
    ]
  }

voteThreshold defaults to 3. Each webhook fires exactly once when votes
transition from below to at-or-above the threshold. Failures are logged to
stderr but never surface as errors to the caller.

- src/webhook.ts: new module with buildPayload, fireWebhook, maybeFireWebhooks
- src/types.ts: add WebhookConfig interface; add webhooks field to SupervisorConfig
- src/categories.ts: extract readConfigJson() helper; add getWebhooks()
- src/store.ts: call maybeFireWebhooks in submitFeedback (dedup path) and upvote
- src/mcp.ts: load webhooks via getWebhooks() and pass to createFeedbackStore
- tests/webhook.test.ts: new tests for threshold logic, multi-webhook, payload, errors
- tests/categories.test.ts: add getWebhooks test suite

Closes #115

Author: igmagollo

src/categories.ts

@@ -1,33 +1,70 @@
 import { resolve, join } from "path";
 import { existsSync, readFileSync } from "fs";
+import type { WebhookConfig } from "./types.js";
 
 export const DEFAULT_CATEGORIES = ["friction", "feature_request", "observation"] as const;
 
+/**
+ * Parse and return the raw config.json object, or null if absent/unparseable.
+ */
+function readConfigJson(dataDir?: string): Record<string, unknown> | null {
+  const dir = dataDir ?? resolve(process.env.SUGGESTION_BOX_DIR ?? ".suggestion-box");
+  const configPath = join(dir, "config.json");
+  if (!existsSync(configPath)) return null;
+  try {
+    return JSON.parse(readFileSync(configPath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Load configured categories from `.suggestion-box/config.json`.
  * Falls back to DEFAULT_CATEGORIES if the config file doesn't exist or
  * doesn't contain a valid `categories` array.
  */
 export function getCategories(): string[] {
-  const dataDir = resolve(process.env.SUGGESTION_BOX_DIR ?? ".suggestion-box");
-  const configPath = join(dataDir, "config.json");
-
-  if (!existsSync(configPath)) {
-    return [...DEFAULT_CATEGORIES];
+  const raw = readConfigJson();
+  if (
+    raw &&
+    Array.isArray(raw.categories) &&
+    raw.categories.length > 0 &&
+    raw.categories.every((c: unknown) => typeof c === "string" && c.length > 0)
+  ) {
+    return raw.categories as string[];
   }
+  return [...DEFAULT_CATEGORIES];
+}
 
-  try {
-    const raw = JSON.parse(readFileSync(configPath, "utf-8"));
-    if (
-      Array.isArray(raw.categories) &&
-      raw.categories.length > 0 &&
-      raw.categories.every((c: unknown) => typeof c === "string" && c.length > 0)
-    ) {
-      return raw.categories;
+/**
+ * Load webhook configurations from `.suggestion-box/config.json`.
+ * Returns an empty array if none are configured or the config is absent.
+ *
+ * Example config.json entry:
+ * ```json
+ * {
+ *   "webhooks": [
+ *     { "url": "https://hooks.slack.com/services/...", "voteThreshold": 3 },
+ *     { "url": "https://discord.com/api/webhooks/...", "voteThreshold": 5 }
+ *   ]
+ * }
+ * ```
+ */
+export function getWebhooks(): WebhookConfig[] {
+  const raw = readConfigJson();
+  if (!raw || !Array.isArray(raw.webhooks)) return [];
+
+  const result: WebhookConfig[] = [];
+  for (const entry of raw.webhooks) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const e = entry as Record<string, unknown>;
+    if (typeof e.url !== "string" || !e.url) continue;
+
+    const wh: WebhookConfig = { url: e.url };
+    if (typeof e.voteThreshold === "number" && e.voteThreshold > 0) {
+      wh.voteThreshold = e.voteThreshold;
     }
-  } catch {
-    // Malformed config — fall back silently
+    result.push(wh);
   }
-
-  return [...DEFAULT_CATEGORIES];
+  return result;
 }

src/mcp.ts

@@ -11,7 +11,7 @@ import {
   publishToGithubSchema,
   triageSchema,
 } from "./schemas.js";
-import { getCategories } from "./categories.js";
+import { getCategories, getWebhooks } from "./categories.js";
 import { checkGhAuth, createGithubIssue } from "./github.js";
 import { assertValidConfig } from "./config.js";
 import { RateLimiter, RateLimitError } from "./rate-limiter.js";
@@ -27,11 +27,13 @@ export async function startMcpServer(): Promise<void> {
     sessionId,
     embed,
     persistent: true,
+    webhooks,
   });
 
   await store.init();
 
   const categories = getCategories();
+  const webhooks = getWebhooks();
   const submitFeedbackSchema = createSubmitFeedbackSchema(categories);
   const listFeedbackSchema = createListFeedbackSchema(categories);
 

src/store.ts

@@ -3,8 +3,10 @@ import { randomUUID } from "crypto";
 import { execSync } from "child_process";
 import { isTrigramMode, trigramSimilarity, DEFAULT_TRIGRAM_THRESHOLD } from "./embedder.js";
 import { getSuggestionBoxVersion } from "./version.js";
+import { maybeFireWebhooks } from "./webhook.js";
 import type {
   SupervisorConfig,
+  WebhookConfig,
   Feedback,
   FeedbackMetadata,
   FeedbackStatus,
@@ -104,6 +106,7 @@ export class FeedbackStore {
   private cachedDb: Database | null = null;
   private readonly useTrigramDedup: boolean;
   private readonly trigramThreshold: number;
+  private readonly webhooks: WebhookConfig[];
 
   constructor(config: SupervisorConfig) {
     this.dbPath = config.dbPath;
@@ -114,6 +117,7 @@ export class FeedbackStore {
     this.persistent = config.persistent ?? false;
     this.useTrigramDedup = isTrigramMode(config.embed);
     this.trigramThreshold = DEFAULT_TRIGRAM_THRESHOLD;
+    this.webhooks = config.webhooks ?? [];
   }
 
   /**
@@ -206,6 +210,7 @@ export class FeedbackStore {
       : await this.findSimilarByEmbedding(input.content, input.targetType, input.targetName);
 
     if (duplicate) {
+      const prevVotes = duplicate.votes;
       await this.withDb(async (db) => {
         await db.prepare(
           "UPDATE feedback SET votes = votes + 1, estimated_tokens_saved = COALESCE(estimated_tokens_saved, 0) + COALESCE(?, 0), estimated_time_saved_minutes = COALESCE(estimated_time_saved_minutes, 0) + COALESCE(?, 0), updated_at = ? WHERE id = ?"
@@ -217,10 +222,18 @@ export class FeedbackStore {
       });
 
       const updated = await this.getFeedbackById(duplicate.id);
+      const newVotes = updated?.votes ?? duplicate.votes + 1;
+
+      if (this.webhooks.length > 0 && updated) {
+        maybeFireWebhooks(updated, prevVotes, this.webhooks).catch((e) =>
+          console.error("[suggestion-box] webhook error:", e)
+        );
+      }
+
       return {
         feedbackId: duplicate.id,
         isDuplicate: true,
-        votes: updated?.votes ?? duplicate.votes + 1,
+        votes: newVotes,
       };
     }
 
@@ -354,6 +367,10 @@ export class FeedbackStore {
     await this.init();
     const now = Math.floor(Date.now() / 1000);
 
+    // Capture prevVotes before the update so we can detect threshold crossings.
+    const before = await this.getFeedbackById(input.feedbackId);
+    const prevVotes = before?.votes ?? 0;
+
     await this.withDb(async (db) => {
       await db.prepare(
         "UPDATE feedback SET votes = votes + 1, estimated_tokens_saved = COALESCE(estimated_tokens_saved, 0) + COALESCE(?, 0), estimated_time_saved_minutes = COALESCE(estimated_time_saved_minutes, 0) + COALESCE(?, 0), updated_at = ? WHERE id = ?"
@@ -365,6 +382,13 @@ export class FeedbackStore {
     });
 
     const feedback = await this.getFeedbackById(input.feedbackId);
+
+    if (this.webhooks.length > 0 && feedback) {
+      maybeFireWebhooks(feedback, prevVotes, this.webhooks).catch((e) =>
+        console.error("[suggestion-box] webhook error:", e)
+      );
+    }
+
     return { votes: feedback?.votes ?? 0 };
   }
 

src/types.ts

@@ -17,6 +17,17 @@ export type FeedbackStatus = "open" | "published" | "dismissed";
 
 export type SortBy = "votes" | "recent" | "impact";
 
+export interface WebhookConfig {
+  /** Webhook URL — supports Slack incoming webhooks, Discord webhooks, or any generic HTTP endpoint. */
+  url: string;
+  /**
+   * Vote count threshold. The webhook fires the first time a feedback item's
+   * vote count crosses this value (transitions from below to >= threshold).
+   * Default: 3.
+   */
+  voteThreshold?: number;
+}
+
 export interface SupervisorConfig {
   /** Path to the Turso database file */
   dbPath: string;
@@ -30,6 +41,11 @@ export interface SupervisorConfig {
   dedupThreshold?: number;
   /** Use a persistent DB connection instead of open/close per operation (default: false) */
   persistent?: boolean;
+  /**
+   * Webhook endpoints to ping when feedback crosses a vote threshold.
+   * Each webhook fires exactly once per threshold crossing.
+   */
+  webhooks?: WebhookConfig[];
 }
 
 /** Version metadata captured at feedback submission time. */

src/webhook.ts

@@ -0,0 +1,88 @@
+import type { Feedback, WebhookConfig } from "./types.js";
+
+export type { WebhookConfig };
+
+/**
+ * Build a JSON payload compatible with both Slack and Discord incoming webhooks.
+ * Slack expects `{ text }`, Discord expects `{ content }`. Sending both keys
+ * works for both platforms; unknown keys are silently ignored.
+ */
+function buildPayload(feedback: Feedback): Record<string, unknown> {
+  const title = feedback.title
+    ? `*${feedback.title}*`
+    : `*[${feedback.category}]* ${feedback.targetType}/${feedback.targetName}`;
+
+  const preview =
+    feedback.content.length > 200
+      ? feedback.content.slice(0, 197) + "..."
+      : feedback.content;
+
+  const lines: string[] = [
+    `:ballot_box_with_ballot: suggestion-box \u2014 high-vote item`,
+    title,
+    `Votes: ${feedback.votes} | Category: ${feedback.category} | Target: ${feedback.targetType}/${feedback.targetName}`,
+    ``,
+    preview,
+    ``,
+    `ID: \`${feedback.id}\``,
+  ];
+
+  const text = lines.join("\n");
+
+  // Slack: `text`, Discord: `content`
+  return { text, content: text };
+}
+
+/**
+ * Fire a single webhook. Failures are non-fatal — errors are logged to stderr
+ * but never thrown so they don't interrupt the feedback submission flow.
+ */
+export async function fireWebhook(url: string, payload: Record<string, unknown>): Promise<void> {
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+
+    if (!response.ok) {
+      console.error(
+        `[suggestion-box] webhook POST to ${url} failed: HTTP ${response.status}`
+      );
+    }
+  } catch (e: any) {
+    console.error(`[suggestion-box] webhook POST to ${url} error: ${e.message}`);
+  }
+}
+
+/**
+ * Check whether a vote transition crosses any configured webhook thresholds
+ * and fire the matching webhooks.
+ *
+ * @param feedback  The updated feedback item (with its new vote count).
+ * @param prevVotes The vote count *before* this update.
+ * @param webhooks  The list of webhook configs to check.
+ */
+export async function maybeFireWebhooks(
+  feedback: Feedback,
+  prevVotes: number,
+  webhooks: WebhookConfig[]
+): Promise<void> {
+  if (webhooks.length === 0) return;
+
+  const newVotes = feedback.votes;
+  const payload = buildPayload(feedback);
+
+  const promises: Promise<void>[] = [];
+  for (const wh of webhooks) {
+    const threshold = wh.voteThreshold ?? 3;
+    // Fire exactly once when the vote count crosses the threshold from below.
+    if (prevVotes < threshold && newVotes >= threshold) {
+      promises.push(fireWebhook(wh.url, payload));
+    }
+  }
+
+  if (promises.length > 0) {
+    await Promise.allSettled(promises);
+  }
+}