feat: webhook relay for false positive reports

New false_positive_relay_url instance setting. When set, every stored
inbound webhook event is POSTed once to that URL as JSON with the inbox
row fields and the original payload forwarded verbatim as a string, so
operators can trigger n8n, Power Automate, or similar automations for
tickets and notifications. Delivery is best effort inside waitUntil
after the durable insert: https only, one attempt, no retry, and a
relay failure never fails or delays the reporting extension. Runbook
documents the payload shape and the hostility assumptions receivers
must keep.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: DailenG

BACKLOG.md

@@ -17,6 +17,11 @@ Current work queue, in order. Update as items land.
       persistence. Entry deleted below per convention.
 - [x] Wiki regeneration for the wizard commit
 - [x] v0.2.0 release (setup wizard; package.json bumped to match)
+- [x] Webhook relay for false positives: `false_positive_relay_url`
+      instance setting; every inbound `/hook/{guid}` event is POSTed once,
+      best effort via waitUntil, as `{source, kind, event}` JSON with
+      payload_json forwarded verbatim; https only; injectable-fetcher unit
+      tests (4); documented in the runbook webhook inbox section.
 
 Queue complete. Next scoped item: GPO deployment artifacts (item 1 below).
 

README.md

@@ -8,7 +8,7 @@ Multi tenant configuration service for the [Check by CyberDrain](https://docs.ch
 
 - **Rules host.** Mirrors the upstream CyberDrain detection rules daily, layers a small per tenant delta on top (extra exclusions, trusted patterns, custom indicators, suppressions), validates everything, and serves each client an immutable published ruleset at an unguessable URL: `/rules/{guid}.json`.
 - **Policy generator.** Renders ready-to-deploy managed policy artifacts per tenant: Chrome and Edge managed storage JSON, Firefox `policies.json` (fragment and full file), `.reg` files for GPO, the variable block for Check's Intune setup script, and the field values for CIPP's Check deployment standard.
-- **Operations dashboard.** Draft and publish with validation gates, one-click rollback, GUID rotation and revocation with hit counters, tenant branding with logo hosting, a webhook inbox for false positive reports, upstream diff history, and an indefinite audit log. Dark mode by default.
+- **Operations dashboard.** Draft and publish with validation gates, one-click rollback, GUID rotation and revocation with hit counters, tenant branding with logo hosting, a webhook inbox for false positive reports with an optional relay that forwards each report to n8n, Power Automate, or any webhook receiver, upstream diff history, and an indefinite audit log. Dark mode by default.
 
 Two delivery paths stay separate by design: detection rules are URL fetched by the extension on its own schedule, while branding and enforcement settings are pushed to browsers via managed storage policy.
 

docs/runbook.md

@@ -143,6 +143,12 @@ The cron runs daily (06:17 UTC). Each sync fetches the CyberDrain rules file; on
 
 False positive reports and other extension events POST to `/hook/{guid}` and land in the Inbox. Payloads are stored verbatim, treated as hostile, and always rendered escaped. Disposition events as reviewed or dismissed; dispositioned events are purged by the daily cleanup, undispositioned ones after the retention window.
 
+**Relay to automations.** Set the **False positive relay URL** instance setting to forward every inbound event to an automation platform (n8n, Power Automate, Zapier, or any webhook receiver) for tickets or notifications. Each event is POSTed once as JSON: `{source, kind, event}` where `event` carries the inbox row (id, tenant id and name, GUID, received time, event type) and the original `payload_json` as a verbatim string. Notes:
+
+- The URL must be `https://`. Platforms like n8n and Power Automate embed a capability token in the URL itself; treat the configured URL as sensitive.
+- Delivery is best effort: one attempt, no retry queue. The Inbox row is the durable record; the relay is a convenience copy, and a failed relay never fails or delays the reporting extension.
+- The relayed `payload_json` is untrusted extension input forwarded verbatim. Automations consuming it must apply the same hostility assumptions this service does: parse defensively, never render unescaped, never execute.
+
 ### Decommissioning a tenant
 
 Revoke all GUIDs, wait for revoked-hit counters to drain (confirming no clients still point at it), then Tenant > Delete. Deletion removes the tenant's rows and R2 objects; audit entries are retained.

src/lib/db.ts

@@ -75,6 +75,9 @@ export const DEFAULT_INSTANCE_SETTINGS: Record<string, string> = {
     "https://raw.githubusercontent.com/CyberDrain/Check/main/rules/detection-rules.json",
   upstream_keep_snapshots: "10",
   version_suffix_label: "cdm",
+  // When set, every inbound webhook event is POSTed to this URL (n8n,
+  // Power Automate, and similar). Empty disables the relay.
+  false_positive_relay_url: "",
   // ISO timestamp once the setup wizard is finished or skipped; empty means
   // the wizard is still offered. Not listed in the Settings page UI.
   onboarding_completed_at: "",

src/lib/relay.ts

@@ -0,0 +1,57 @@
+// Outbound relay for inbound webhook reports (false positives and similar).
+// When the false_positive_relay_url instance setting is set, every stored
+// webhook event is POSTed to it as JSON, so operators can trigger n8n,
+// Power Automate, or comparable automations (tickets, notifications).
+//
+// Delivery is best effort: one attempt inside waitUntil, no queue and no
+// retry, matching the zero-infrastructure design. The extension retries
+// nothing either; the inbox row is the durable record and the relay is a
+// convenience copy. payload_json is forwarded verbatim as a string, never
+// parsed or interpreted here; receivers must treat it as hostile input.
+import type { Env } from "../types";
+import { getInstanceSettings } from "./db";
+
+export interface RelayEvent {
+  id: string;
+  tenant_id: string;
+  tenant_name: string;
+  guid: string;
+  received_at: string;
+  event_type: string;
+  payload_json: string;
+}
+
+export type RelayOutcome =
+  | { status: "skipped" }
+  | { status: "sent"; httpStatus: number }
+  | { status: "failed"; error: string };
+
+export async function relayWebhookEvent(
+  env: Env,
+  event: RelayEvent,
+  fetcher: typeof fetch = fetch,
+): Promise<RelayOutcome> {
+  const settings = await getInstanceSettings(env.DB);
+  const url = (settings.false_positive_relay_url ?? "").trim();
+  if (url === "") return { status: "skipped" };
+  if (!/^https:\/\//i.test(url)) {
+    return { status: "failed", error: "relay URL must start with https://" };
+  }
+  try {
+    const response = await fetcher(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        source: "checkdeploymanager",
+        kind: "webhook_event",
+        event,
+      }),
+    });
+    if (!response.ok) {
+      return { status: "failed", error: `HTTP ${response.status}` };
+    }
+    return { status: "sent", httpStatus: response.status };
+  } catch (error) {
+    return { status: "failed", error: String(error) };
+  }
+}

src/routes/hook.ts

@@ -2,7 +2,8 @@
 // as hostile: never interpreted, always HTML-escaped when rendered.
 import { Hono } from "hono";
 import type { Env } from "../types";
-import { getActiveGuid, newId, nowIso } from "../lib/db";
+import { getActiveGuid, getTenant, newId, nowIso } from "../lib/db";
+import { relayWebhookEvent } from "../lib/relay";
 
 export const MAX_HOOK_BYTES = 256 * 1024;
 
@@ -41,12 +42,34 @@ hookRoutes.post("/hook/:guid", async (c) => {
     return c.json({ error: "body is not valid JSON" }, 400);
   }
 
+  const eventId = newId();
+  const receivedAt = nowIso();
   await c.env.DB.prepare(
     "INSERT INTO webhook_events (id, tenant_id, guid, received_at, event_type, payload_json) " +
       "VALUES (?, ?, ?, ?, ?, ?)",
   )
-    .bind(newId(), guidRow.tenant_id, guidRow.guid, nowIso(), eventType, body)
+    .bind(eventId, guidRow.tenant_id, guidRow.guid, receivedAt, eventType, body)
     .run();
 
+  // Best-effort relay after the durable insert; never delays or fails the
+  // extension's request.
+  c.executionCtx.waitUntil(
+    (async () => {
+      const tenant = await getTenant(c.env.DB, guidRow.tenant_id);
+      const outcome = await relayWebhookEvent(c.env, {
+        id: eventId,
+        tenant_id: guidRow.tenant_id,
+        tenant_name: tenant?.name ?? "",
+        guid: guidRow.guid,
+        received_at: receivedAt,
+        event_type: eventType,
+        payload_json: body,
+      });
+      if (outcome.status === "failed") {
+        console.log(`webhook relay failed: ${outcome.error}`);
+      }
+    })(),
+  );
+
   return c.json({ received: true });
 });

src/ui/manage/app.js

@@ -857,6 +857,7 @@ async function renderUpstream() {
 const SETTING_LABELS = [
   ["public_base_url", "Public base URL (e.g. https://check.example.com; used in every generated artifact)"],
   ["default_cipp_server_url", "Default CIPP server URL (blank disables CIPP unless a tenant overrides)"],
+  ["false_positive_relay_url", "False positive relay URL (every inbound webhook report is POSTed here as JSON; for n8n, Power Automate, and similar; blank disables)"],
   ["upstream_source_url", "Upstream rules source URL"],
   ["version_suffix_label", "Version suffix label (published versions read upstream+label.n)"],
   ["metrics_retention_days", "Fetch metrics retention (days)"],

test/relay.test.ts

@@ -0,0 +1,70 @@
+import { env } from "cloudflare:test";
+import { describe, expect, it } from "vitest";
+import { relayWebhookEvent, type RelayEvent } from "../src/lib/relay";
+import { putInstanceSetting } from "../src/lib/db";
+import { fetcherFailing, fetcherReturning, SAMPLE_GUID, SAMPLE_TENANT_NAME } from "./helpers";
+
+function sampleEvent(): RelayEvent {
+  return {
+    id: "00000000-0000-4000-8000-000000000000",
+    tenant_id: "00000000-0000-4000-8000-000000000000",
+    tenant_name: SAMPLE_TENANT_NAME,
+    guid: SAMPLE_GUID,
+    received_at: "2026-07-03T00:00:00.000Z",
+    event_type: "false_positive_report",
+    payload_json: '{"reportType":"false_positive_report","url":"https://login.example.com"}',
+  };
+}
+
+function fetcherCapturing(captured: { url?: string; body?: string }): typeof fetch {
+  return (async (url: any, init: any) => {
+    captured.url = String(url);
+    captured.body = String(init?.body ?? "");
+    return new Response("ok", { status: 200 });
+  }) as typeof fetch;
+}
+
+function fetcherRefusing(): typeof fetch {
+  return (async () => {
+    throw new Error("relay fetch must not be called when disabled");
+  }) as typeof fetch;
+}
+
+describe("webhook relay", () => {
+  it("skips without calling out when no relay URL is configured", async () => {
+    const outcome = await relayWebhookEvent(env, sampleEvent(), fetcherRefusing());
+    expect(outcome).toEqual({ status: "skipped" });
+  });
+
+  it("POSTs the event as JSON to the configured URL", async () => {
+    await putInstanceSetting(env.DB, "false_positive_relay_url", "https://hooks.example.test/relay");
+    const captured: { url?: string; body?: string } = {};
+    const outcome = await relayWebhookEvent(env, sampleEvent(), fetcherCapturing(captured));
+    expect(outcome).toEqual({ status: "sent", httpStatus: 200 });
+    expect(captured.url).toBe("https://hooks.example.test/relay");
+    const sent = JSON.parse(captured.body ?? "{}");
+    expect(sent.source).toBe("checkdeploymanager");
+    expect(sent.kind).toBe("webhook_event");
+    expect(sent.event.tenant_name).toBe(SAMPLE_TENANT_NAME);
+    expect(sent.event.event_type).toBe("false_positive_report");
+    // The payload travels verbatim as a string, never parsed by the relay.
+    expect(typeof sent.event.payload_json).toBe("string");
+  });
+
+  it("rejects non-https relay URLs", async () => {
+    await putInstanceSetting(env.DB, "false_positive_relay_url", "http://insecure.example.test/hook");
+    const outcome = await relayWebhookEvent(env, sampleEvent(), fetcherRefusing());
+    expect(outcome).toEqual({
+      status: "failed",
+      error: "relay URL must start with https://",
+    });
+  });
+
+  it("reports failure on network errors and non-2xx responses", async () => {
+    await putInstanceSetting(env.DB, "false_positive_relay_url", "https://hooks.example.test/relay");
+    const network = await relayWebhookEvent(env, sampleEvent(), fetcherFailing());
+    expect(network.status).toBe("failed");
+    const http = await relayWebhookEvent(env, sampleEvent(), fetcherReturning("nope", 500));
+    expect(http).toEqual({ status: "failed", error: "HTTP 500" });
+  });
+});