feat(slack): add HTTP receiver webhook mode (#1143) - thanks @jdrhyne

Co-authored-by: Jonathan Rhyne <jdrhyne@users.noreply.github.com>

src/config/slack-http-config.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+
+import { validateConfigObject } from "./config.js";
+
+describe("Slack HTTP mode config", () => {
+  it("accepts HTTP mode when signing secret is configured", () => {
+    const res = validateConfigObject({
+      channels: {
+        slack: {
+          mode: "http",
+          signingSecret: "secret",
+        },
+      },
+    });
+    expect(res.ok).toBe(true);
+  });
+
+  it("rejects HTTP mode without signing secret", () => {
+    const res = validateConfigObject({
+      channels: {
+        slack: {
+          mode: "http",
+        },
+      },
+    });
+    expect(res.ok).toBe(false);
+    if (!res.ok) {
+      expect(res.issues[0]?.path).toBe("channels.slack.signingSecret");
+    }
+  });
+
+  it("accepts account HTTP mode when base signing secret is set", () => {
+    const res = validateConfigObject({
+      channels: {
+        slack: {
+          signingSecret: "secret",
+          accounts: {
+            ops: {
+              mode: "http",
+            },
+          },
+        },
+      },
+    });
+    expect(res.ok).toBe(true);
+  });
+
+  it("rejects account HTTP mode without signing secret", () => {
+    const res = validateConfigObject({
+      channels: {
+        slack: {
+          accounts: {
+            ops: {
+              mode: "http",
+            },
+          },
+        },
+      },
+    });
+    expect(res.ok).toBe(false);
+    if (!res.ok) {
+      expect(res.issues[0]?.path).toBe("channels.slack.accounts.ops.signingSecret");
+    }
+  });
+});

src/config/types.slack.ts

@@ -70,6 +70,12 @@ export type SlackThreadConfig = {
 export type SlackAccountConfig = {
   /** Optional display name for this account (used in CLI/UI lists). */
   name?: string;
+  /** Slack connection mode (socket|http). Default: socket. */
+  mode?: "socket" | "http";
+  /** Slack signing secret (required for HTTP mode). */
+  signingSecret?: string;
+  /** Slack Events API webhook path (default: /slack/events). */
+  webhookPath?: string;
   /** Optional provider capability tags used for agent/runtime guidance. */
   capabilities?: string[];
   /** Override native command registration for Slack (bool or "auto"). */

src/config/zod-schema.providers-core.ts

@@ -258,6 +258,9 @@ export const SlackThreadSchema = z.object({
 
 export const SlackAccountSchema = z.object({
   name: z.string().optional(),
+  mode: z.enum(["socket", "http"]).optional(),
+  signingSecret: z.string().optional(),
+  webhookPath: z.string().optional(),
   capabilities: z.array(z.string()).optional(),
   enabled: z.boolean().optional(),
   commands: ProviderCommandsSchema,
@@ -305,7 +308,35 @@ export const SlackAccountSchema = z.object({
 });
 
 export const SlackConfigSchema = SlackAccountSchema.extend({
+  mode: z.enum(["socket", "http"]).optional().default("socket"),
+  signingSecret: z.string().optional(),
+  webhookPath: z.string().optional().default("/slack/events"),
   accounts: z.record(z.string(), SlackAccountSchema.optional()).optional(),
+}).superRefine((value, ctx) => {
+  const baseMode = value.mode ?? "socket";
+  if (baseMode === "http" && !value.signingSecret) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'channels.slack.mode="http" requires channels.slack.signingSecret',
+      path: ["signingSecret"],
+    });
+  }
+  if (!value.accounts) return;
+  for (const [accountId, account] of Object.entries(value.accounts)) {
+    if (!account) continue;
+    if (account.enabled === false) continue;
+    const accountMode = account.mode ?? baseMode;
+    if (accountMode !== "http") continue;
+    const accountSecret = account.signingSecret ?? value.signingSecret;
+    if (!accountSecret) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          'channels.slack.accounts.*.mode="http" requires channels.slack.signingSecret or channels.slack.accounts.*.signingSecret',
+        path: ["accounts", accountId, "signingSecret"],
+      });
+    }
+  }
 });
 
 export const SignalAccountSchemaBase = z.object({

src/gateway/server-http.ts

@@ -8,6 +8,7 @@ import type { WebSocketServer } from "ws";
 import { handleA2uiHttpRequest } from "../canvas-host/a2ui.js";
 import type { CanvasHostHandler } from "../canvas-host/server.js";
 import type { createSubsystemLogger } from "../logging.js";
+import { handleSlackHttpRequest } from "../slack/http/index.js";
 import { handleControlUiHttpRequest } from "./control-ui.js";
 import {
   extractHookToken,
@@ -208,6 +209,7 @@ export function createGatewayHttpServer(opts: {
 
     void (async () => {
       if (await handleHooksRequest(req, res)) return;
+      if (await handleSlackHttpRequest(req, res)) return;
       if (handlePluginRequest && (await handlePluginRequest(req, res))) return;
       if (openAiChatCompletionsEnabled) {
         if (await handleOpenAiHttpRequest(req, res, { auth: resolvedAuth })) return;

src/gateway/server-runtime-state.ts

@@ -20,9 +20,7 @@ import type { DedupeEntry } from "./server-shared.js";
 import type { PluginRegistry } from "../plugins/registry.js";
 
 export async function createGatewayRuntimeState(params: {
-  cfg: {
-    canvasHost?: { root?: string; enabled?: boolean; liveReload?: boolean };
-  };
+  cfg: import("../config/config.js").ClawdbotConfig;
   bindHost: string;
   port: number;
   controlUiEnabled: boolean;

src/slack/http/index.ts

@@ -0,0 +1 @@
+export * from "./registry.js";

src/slack/http/registry.test.ts

@@ -0,0 +1,87 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  handleSlackHttpRequest,
+  normalizeSlackWebhookPath,
+  registerSlackHttpHandler,
+} from "./registry.js";
+
+describe("normalizeSlackWebhookPath", () => {
+  it("returns the default path when input is empty", () => {
+    expect(normalizeSlackWebhookPath()).toBe("/slack/events");
+    expect(normalizeSlackWebhookPath(" ")).toBe("/slack/events");
+  });
+
+  it("ensures a leading slash", () => {
+    expect(normalizeSlackWebhookPath("slack/events")).toBe("/slack/events");
+    expect(normalizeSlackWebhookPath("/hooks/slack")).toBe("/hooks/slack");
+  });
+});
+
+describe("registerSlackHttpHandler", () => {
+  const unregisters: Array<() => void> = [];
+
+  afterEach(() => {
+    for (const unregister of unregisters.splice(0)) unregister();
+  });
+
+  it("routes requests to a registered handler", async () => {
+    const handler = vi.fn();
+    unregisters.push(
+      registerSlackHttpHandler({
+        path: "/slack/events",
+        handler,
+      }),
+    );
+
+    const req = { url: "/slack/events?foo=bar" } as IncomingMessage;
+    const res = {} as ServerResponse;
+
+    const handled = await handleSlackHttpRequest(req, res);
+
+    expect(handled).toBe(true);
+    expect(handler).toHaveBeenCalledWith(req, res);
+  });
+
+  it("returns false when no handler matches", async () => {
+    const req = { url: "/slack/other" } as IncomingMessage;
+    const res = {} as ServerResponse;
+
+    const handled = await handleSlackHttpRequest(req, res);
+
+    expect(handled).toBe(false);
+  });
+
+  it("logs and ignores duplicate registrations", async () => {
+    const handler = vi.fn();
+    const log = vi.fn();
+    unregisters.push(
+      registerSlackHttpHandler({
+        path: "/slack/events",
+        handler,
+        log,
+        accountId: "primary",
+      }),
+    );
+    unregisters.push(
+      registerSlackHttpHandler({
+        path: "/slack/events",
+        handler: vi.fn(),
+        log,
+        accountId: "duplicate",
+      }),
+    );
+
+    const req = { url: "/slack/events" } as IncomingMessage;
+    const res = {} as ServerResponse;
+
+    const handled = await handleSlackHttpRequest(req, res);
+
+    expect(handled).toBe(true);
+    expect(handler).toHaveBeenCalledWith(req, res);
+    expect(log).toHaveBeenCalledWith(
+      'slack: webhook path /slack/events already registered for account "duplicate"',
+    );
+  });
+});

src/slack/http/registry.ts

@@ -0,0 +1,45 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+export type SlackHttpRequestHandler = (
+  req: IncomingMessage,
+  res: ServerResponse,
+) => Promise<void> | void;
+
+type RegisterSlackHttpHandlerArgs = {
+  path?: string | null;
+  handler: SlackHttpRequestHandler;
+  log?: (message: string) => void;
+  accountId?: string;
+};
+
+const slackHttpRoutes = new Map<string, SlackHttpRequestHandler>();
+
+export function normalizeSlackWebhookPath(path?: string | null): string {
+  const trimmed = path?.trim();
+  if (!trimmed) return "/slack/events";
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+
+export function registerSlackHttpHandler(params: RegisterSlackHttpHandlerArgs): () => void {
+  const normalizedPath = normalizeSlackWebhookPath(params.path);
+  if (slackHttpRoutes.has(normalizedPath)) {
+    const suffix = params.accountId ? ` for account "${params.accountId}"` : "";
+    params.log?.(`slack: webhook path ${normalizedPath} already registered${suffix}`);
+    return () => {};
+  }
+  slackHttpRoutes.set(normalizedPath, params.handler);
+  return () => {
+    slackHttpRoutes.delete(normalizedPath);
+  };
+}
+
+export async function handleSlackHttpRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<boolean> {
+  const url = new URL(req.url ?? "/", "http://localhost");
+  const handler = slackHttpRoutes.get(url.pathname);
+  if (!handler) return false;
+  await handler(req, res);
+  return true;
+}

src/slack/monitor/provider.ts

@@ -1,4 +1,6 @@
-import { App } from "@slack/bolt";
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import { App, HTTPReceiver } from "@slack/bolt";
 
 import { resolveTextChunkLimit } from "../../auto-reply/chunk.js";
 import { DEFAULT_GROUP_HISTORY_LIMIT } from "../../auto-reply/reply/history.js";
@@ -14,6 +16,7 @@ import { resolveSlackAccount } from "../accounts.js";
 import { resolveSlackChannelAllowlist } from "../resolve-channels.js";
 import { resolveSlackUserAllowlist } from "../resolve-users.js";
 import { resolveSlackAppToken, resolveSlackBotToken } from "../token.js";
+import { normalizeSlackWebhookPath, registerSlackHttpHandler } from "../http/index.js";
 import { resolveSlackSlashCommandConfig } from "./commands.js";
 import { createSlackMonitorContext } from "./context.js";
 import { registerSlackMonitorEvents } from "./events.js";
@@ -49,11 +52,21 @@ export async function monitorSlackProvider(opts: MonitorSlackOpts = {}) {
   const sessionScope: SessionScope = sessionCfg?.scope ?? "per-sender";
   const mainKey = normalizeMainKey(sessionCfg?.mainKey);
 
+  const slackMode = opts.mode ?? account.config.mode ?? "socket";
+  const slackWebhookPath = normalizeSlackWebhookPath(account.config.webhookPath);
+  const signingSecret = account.config.signingSecret?.trim();
   const botToken = resolveSlackBotToken(opts.botToken ?? account.botToken);
   const appToken = resolveSlackAppToken(opts.appToken ?? account.appToken);
-  if (!botToken || !appToken) {
+  if (!botToken || (slackMode !== "http" && !appToken)) {
+    const missing =
+      slackMode === "http"
+        ? `Slack bot token missing for account "${account.accountId}" (set channels.slack.accounts.${account.accountId}.botToken or SLACK_BOT_TOKEN for default).`
+        : `Slack bot + app tokens missing for account "${account.accountId}" (set channels.slack.accounts.${account.accountId}.botToken/appToken or SLACK_BOT_TOKEN/SLACK_APP_TOKEN for default).`;
+    throw new Error(missing);
+  }
+  if (slackMode === "http" && !signingSecret) {
     throw new Error(
-      `Slack bot + app tokens missing for account "${account.accountId}" (set channels.slack.accounts.${account.accountId}.botToken/appToken or SLACK_BOT_TOKEN/SLACK_APP_TOKEN for default).`,
+      `Slack signing secret missing for account "${account.accountId}" (set channels.slack.signingSecret or channels.slack.accounts.${account.accountId}.signingSecret).`,
     );
   }
 
@@ -102,11 +115,32 @@ export async function monitorSlackProvider(opts: MonitorSlackOpts = {}) {
   const mediaMaxBytes = (opts.mediaMaxMb ?? slackCfg.mediaMaxMb ?? 20) * 1024 * 1024;
   const removeAckAfterReply = cfg.messages?.removeAckAfterReply ?? false;
 
-  const app = new App({
-    token: botToken,
-    appToken,
-    socketMode: true,
-  });
+  const receiver =
+    slackMode === "http"
+      ? new HTTPReceiver({
+          signingSecret: signingSecret ?? "",
+          endpoints: slackWebhookPath,
+        })
+      : null;
+  const app = new App(
+    slackMode === "socket"
+      ? {
+          token: botToken,
+          appToken,
+          socketMode: true,
+        }
+      : {
+          token: botToken,
+          receiver: receiver ?? undefined,
+        },
+  );
+  const slackHttpHandler =
+    slackMode === "http" && receiver
+      ? async (req: IncomingMessage, res: ServerResponse) => {
+          await Promise.resolve(receiver.requestListener(req, res));
+        }
+      : null;
+  let unregisterHttpHandler: (() => void) | null = null;
 
   let botUserId = "";
   let teamId = "";
@@ -164,6 +198,14 @@ export async function monitorSlackProvider(opts: MonitorSlackOpts = {}) {
 
   registerSlackMonitorEvents({ ctx, account, handleSlackMessage });
   registerSlackMonitorSlashCommands({ ctx, account });
+  if (slackMode === "http" && slackHttpHandler) {
+    unregisterHttpHandler = registerSlackHttpHandler({
+      path: slackWebhookPath,
+      handler: slackHttpHandler,
+      log: runtime.log,
+      accountId: account.accountId,
+    });
+  }
 
   if (resolveToken) {
     void (async () => {
@@ -284,13 +326,17 @@ export async function monitorSlackProvider(opts: MonitorSlackOpts = {}) {
   }
 
   const stopOnAbort = () => {
-    if (opts.abortSignal?.aborted) void app.stop();
+    if (opts.abortSignal?.aborted && slackMode === "socket") void app.stop();
   };
   opts.abortSignal?.addEventListener("abort", stopOnAbort, { once: true });
 
   try {
-    await app.start();
-    runtime.log?.("slack socket mode connected");
+    if (slackMode === "socket") {
+      await app.start();
+      runtime.log?.("slack socket mode connected");
+    } else {
+      runtime.log?.(`slack http mode listening at ${slackWebhookPath}`);
+    }
     if (opts.abortSignal?.aborted) return;
     await new Promise<void>((resolve) => {
       opts.abortSignal?.addEventListener("abort", () => resolve(), {
@@ -299,6 +345,7 @@ export async function monitorSlackProvider(opts: MonitorSlackOpts = {}) {
     });
   } finally {
     opts.abortSignal?.removeEventListener("abort", stopOnAbort);
+    unregisterHttpHandler?.();
     await app.stop().catch(() => undefined);
   }
 }