@elizaos/plugin-webhooks 2.0.0-alpha.3

package/dist/index.d.ts

@@ -0,0 +1,138 @@
+import { Plugin } from '@elizaos/core';
+
+/**
+ * @module auth
+ * @description Token-based authentication for webhook endpoints.
+ *
+ * Supports three methods (in priority order):
+ *   1. Authorization: Bearer <token>
+ *   2. x-otto-token: <token>
+ *   3. ?token=<token> (deprecated, logs a warning)
+ */
+declare function extractToken(req: {
+    headers?: Record<string, string | string[] | undefined>;
+    query?: Record<string, string | string[]>;
+    url?: string;
+}): string | undefined;
+declare function validateToken(req: {
+    headers?: Record<string, string | string[] | undefined>;
+    query?: Record<string, string | string[]>;
+    url?: string;
+}, expectedToken: string): boolean;
+
+/**
+ * @module mappings
+ * @description Hook mapping resolution and template rendering.
+ *
+ * Mappings let you define how arbitrary webhook payloads (like Gmail Pub/Sub)
+ * are transformed into wake or agent actions.
+ *
+ * Config shape (from Otto/openclaw):
+ *   hooks.mappings: [
+ *     {
+ *       match: { path: "gmail" },
+ *       action: "agent",
+ *       name: "Gmail",
+ *       sessionKey: "hook:gmail:{{messages[0].id}}",
+ *       messageTemplate: "New email from {{messages[0].from}}...",
+ *       wakeMode: "now",
+ *       deliver: true,
+ *       channel: "last",
+ *     }
+ *   ]
+ */
+interface HookMapping {
+    match?: {
+        path?: string;
+        source?: string;
+    };
+    action?: "wake" | "agent";
+    wakeMode?: "now" | "next-heartbeat";
+    name?: string;
+    sessionKey?: string;
+    messageTemplate?: string;
+    textTemplate?: string;
+    deliver?: boolean;
+    channel?: string;
+    to?: string;
+    model?: string;
+    thinking?: string;
+    timeoutSeconds?: number;
+    allowUnsafeExternalContent?: boolean;
+}
+/**
+ * Find a mapping that matches the given hook name (path segment after /hooks/).
+ */
+declare function findMapping(mappings: HookMapping[], hookName: string, payload: Record<string, unknown>): HookMapping | undefined;
+/**
+ * Render a Mustache-style template against a data object.
+ *
+ * Supports:
+ *   {{field}}            -> data.field
+ *   {{nested.field}}     -> data.nested.field
+ *   {{array[0].field}}   -> data.array[0].field
+ *
+ * Unresolved placeholders are left as-is.
+ */
+declare function renderTemplate(template: string, data: Record<string, unknown>): string;
+/**
+ * Apply a mapping to a payload, producing the final wake or agent parameters.
+ */
+declare function applyMapping(mapping: HookMapping, hookName: string, payload: Record<string, unknown>): {
+    action: "wake" | "agent";
+    text?: string;
+    message?: string;
+    name?: string;
+    sessionKey?: string;
+    wakeMode: "now" | "next-heartbeat";
+    deliver?: boolean;
+    channel?: string;
+    to?: string;
+    model?: string;
+    thinking?: string;
+    timeoutSeconds?: number;
+};
+
+/**
+ * @module plugin-webhooks
+ * @description ElizaOS plugin for HTTP webhook ingress.
+ *
+ * Exposes three route groups via the plugin `routes` array:
+ *   POST /hooks/wake      - Enqueue system event + optional immediate heartbeat
+ *   POST /hooks/agent     - Run isolated agent turn + optional delivery
+ *   POST /hooks/:name     - Mapped webhook (resolves via hooks.mappings config)
+ *
+ * No separate HTTP server is created – routes register on the runtime's
+ * existing HTTP server via the Eliza plugin system.
+ *
+ * Cross-plugin communication:
+ *   Emits HEARTBEAT_WAKE and HEARTBEAT_SYSTEM_EVENT events which are
+ *   consumed by @elizaos/plugin-cron's heartbeat worker.
+ *
+ * @example Config (character.settings):
+ * ```json5
+ * {
+ *   hooks: {
+ *     enabled: true,
+ *     token: "shared-secret",
+ *     presets: ["gmail"],
+ *     mappings: [
+ *       {
+ *         match: { path: "github" },
+ *         action: "agent",
+ *         name: "GitHub",
+ *         messageTemplate: "New event: {{action}} on {{repository.full_name}}",
+ *         wakeMode: "now",
+ *         deliver: true,
+ *         channel: "discord",
+ *         to: "channel:123456789",
+ *       }
+ *     ],
+ *   }
+ * }
+ * ```
+ */
+
+declare const webhooksPlugin: Plugin;
+
+export { type HookMapping, applyMapping, webhooksPlugin as default, extractToken, findMapping, renderTemplate, validateToken, webhooksPlugin };

package/dist/index.js

@@ -0,0 +1,465 @@
+// src/handlers.ts
+import {
+  ChannelType,
+  logger as logger2,
+  stringToUuid
+} from "@elizaos/core";
+
+// ../../../../node_modules/uuid/dist/esm/stringify.js
+var byteToHex = [];
+for (let i = 0; i < 256; ++i) {
+  byteToHex.push((i + 256).toString(16).slice(1));
+}
+function unsafeStringify(arr, offset = 0) {
+  return (byteToHex[arr[offset + 0]] + byteToHex[arr[offset + 1]] + byteToHex[arr[offset + 2]] + byteToHex[arr[offset + 3]] + "-" + byteToHex[arr[offset + 4]] + byteToHex[arr[offset + 5]] + "-" + byteToHex[arr[offset + 6]] + byteToHex[arr[offset + 7]] + "-" + byteToHex[arr[offset + 8]] + byteToHex[arr[offset + 9]] + "-" + byteToHex[arr[offset + 10]] + byteToHex[arr[offset + 11]] + byteToHex[arr[offset + 12]] + byteToHex[arr[offset + 13]] + byteToHex[arr[offset + 14]] + byteToHex[arr[offset + 15]]).toLowerCase();
+}
+
+// ../../../../node_modules/uuid/dist/esm/rng.js
+import { randomFillSync } from "crypto";
+var rnds8Pool = new Uint8Array(256);
+var poolPtr = rnds8Pool.length;
+function rng() {
+  if (poolPtr > rnds8Pool.length - 16) {
+    randomFillSync(rnds8Pool);
+    poolPtr = 0;
+  }
+  return rnds8Pool.slice(poolPtr, poolPtr += 16);
+}
+
+// ../../../../node_modules/uuid/dist/esm/native.js
+import { randomUUID } from "crypto";
+var native_default = { randomUUID };
+
+// ../../../../node_modules/uuid/dist/esm/v4.js
+function v4(options, buf, offset) {
+  if (native_default.randomUUID && !buf && !options) {
+    return native_default.randomUUID();
+  }
+  options = options || {};
+  const rnds = options.random ?? options.rng?.() ?? rng();
+  if (rnds.length < 16) {
+    throw new Error("Random bytes length must be >= 16");
+  }
+  rnds[6] = rnds[6] & 15 | 64;
+  rnds[8] = rnds[8] & 63 | 128;
+  if (buf) {
+    offset = offset || 0;
+    if (offset < 0 || offset + 16 > buf.length) {
+      throw new RangeError(`UUID byte range ${offset}:${offset + 15} is out of buffer bounds`);
+    }
+    for (let i = 0; i < 16; ++i) {
+      buf[offset + i] = rnds[i];
+    }
+    return buf;
+  }
+  return unsafeStringify(rnds);
+}
+var v4_default = v4;
+
+// src/auth.ts
+import { timingSafeEqual } from "crypto";
+import { logger } from "@elizaos/core";
+function extractToken(req) {
+  const headers = req.headers ?? {};
+  const authHeader = headers.authorization ?? headers.Authorization;
+  const authStr = Array.isArray(authHeader) ? authHeader[0] : authHeader;
+  if (typeof authStr === "string" && authStr.startsWith("Bearer ")) {
+    return authStr.slice(7).trim();
+  }
+  const ottoHeader = headers["x-otto-token"] ?? headers["X-Otto-Token"];
+  const ottoStr = Array.isArray(ottoHeader) ? ottoHeader[0] : ottoHeader;
+  if (typeof ottoStr === "string" && ottoStr.trim()) {
+    return ottoStr.trim();
+  }
+  let queryToken;
+  if (req.query && typeof req.query.token === "string") {
+    queryToken = req.query.token;
+  } else if (typeof req.url === "string") {
+    const url = new URL(req.url, "http://localhost");
+    queryToken = url.searchParams.get("token") ?? void 0;
+  }
+  if (queryToken) {
+    logger.warn(
+      "[Webhooks] Query-param token auth is deprecated; use Authorization header instead"
+    );
+    return queryToken.trim();
+  }
+  return void 0;
+}
+function validateToken(req, expectedToken) {
+  const provided = extractToken(req);
+  if (!provided) {
+    return false;
+  }
+  const providedBuf = Buffer.from(provided, "utf-8");
+  const expectedBuf = Buffer.from(expectedToken, "utf-8");
+  if (providedBuf.length !== expectedBuf.length) {
+    return false;
+  }
+  return timingSafeEqual(providedBuf, expectedBuf);
+}
+
+// src/mappings.ts
+function findMapping(mappings, hookName, payload) {
+  for (const mapping of mappings) {
+    if (mapping.match?.path && mapping.match.path === hookName) {
+      return mapping;
+    }
+    if (mapping.match?.source && typeof payload.source === "string") {
+      if (payload.source === mapping.match.source) {
+        return mapping;
+      }
+    }
+  }
+  return void 0;
+}
+function renderTemplate(template, data) {
+  return template.replace(/\{\{([^}]+)\}\}/g, (_match, expr) => {
+    const path = expr.trim();
+    const value = resolvePath(data, path);
+    if (value === void 0 || value === null) {
+      return `{{${expr}}}`;
+    }
+    if (typeof value === "object") {
+      return JSON.stringify(value);
+    }
+    return String(value);
+  });
+}
+function resolvePath(obj, path) {
+  const normalizedPath = path.replace(/\[(\d+)\]/g, ".$1");
+  const parts = normalizedPath.split(".");
+  let current = obj;
+  for (const part of parts) {
+    if (current === null || current === void 0) {
+      return void 0;
+    }
+    if (typeof current === "object") {
+      current = current[part];
+    } else {
+      return void 0;
+    }
+  }
+  return current;
+}
+function applyMapping(mapping, hookName, payload) {
+  const action = mapping.action ?? "agent";
+  const wakeMode = mapping.wakeMode ?? "now";
+  if (action === "wake") {
+    const textTemplate = mapping.textTemplate ?? mapping.messageTemplate;
+    const text = textTemplate ? renderTemplate(textTemplate, payload) : typeof payload.text === "string" ? payload.text : `Webhook received: ${hookName}`;
+    return { action: "wake", text, wakeMode };
+  }
+  const messageTemplate = mapping.messageTemplate;
+  const message = messageTemplate ? renderTemplate(messageTemplate, payload) : typeof payload.message === "string" ? payload.message : `Webhook payload from ${hookName}`;
+  const sessionKey = mapping.sessionKey ? renderTemplate(mapping.sessionKey, payload) : `hook:${hookName}:${Date.now()}`;
+  return {
+    action: "agent",
+    message,
+    name: mapping.name ?? hookName,
+    sessionKey,
+    wakeMode,
+    deliver: mapping.deliver ?? true,
+    channel: mapping.channel ?? "last",
+    to: mapping.to,
+    model: mapping.model,
+    thinking: mapping.thinking,
+    timeoutSeconds: mapping.timeoutSeconds
+  };
+}
+
+// src/handlers.ts
+var GMAIL_PRESET_MAPPING = {
+  match: { path: "gmail" },
+  action: "agent",
+  name: "Gmail",
+  sessionKey: "hook:gmail:{{messages[0].id}}",
+  messageTemplate: "New email from {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}\n{{messages[0].body}}",
+  wakeMode: "now",
+  deliver: true,
+  channel: "last"
+};
+function resolveHooksConfig(runtime) {
+  const settings = runtime.character?.settings ?? {};
+  const hooks = settings.hooks ?? {};
+  if (hooks.enabled === false) {
+    return null;
+  }
+  const token = typeof hooks.token === "string" ? hooks.token.trim() : "";
+  if (!token) {
+    return null;
+  }
+  const rawMappings = Array.isArray(hooks.mappings) ? hooks.mappings : [];
+  const mappings = rawMappings.filter(
+    (m) => typeof m === "object" && m !== null
+  );
+  const presets = Array.isArray(hooks.presets) ? hooks.presets.filter((p) => typeof p === "string") : [];
+  if (presets.includes("gmail")) {
+    const hasGmailMapping = mappings.some((m) => m.match?.path === "gmail");
+    if (!hasGmailMapping) {
+      mappings.push(GMAIL_PRESET_MAPPING);
+    }
+  }
+  return { token, mappings, presets };
+}
+async function deliverToChannel(runtime, content, channel, to) {
+  let source;
+  let channelId;
+  if (channel !== "last") {
+    source = channel;
+    channelId = to;
+  } else {
+    const internalSources = /* @__PURE__ */ new Set(["cron", "webhook", "heartbeat", "internal"]);
+    const rooms = await runtime.getRooms(runtime.agentId).catch(() => []);
+    let found = false;
+    for (const room of rooms) {
+      if (room.source && !internalSources.has(room.source)) {
+        source = room.source;
+        channelId = to ?? room.channelId ?? void 0;
+        found = true;
+        break;
+      }
+    }
+    if (!found) {
+      logger2.warn(`[Webhooks] No delivery target resolved for channel "last"`);
+      return;
+    }
+    source = source;
+  }
+  await runtime.sendMessageToTarget({ source, channelId }, content);
+  logger2.info(`[Webhooks] Delivered to ${source}${channelId ? `:${channelId}` : ""}`);
+}
+async function emitHeartbeatWake(runtime, text, source) {
+  await runtime.emitEvent("HEARTBEAT_WAKE", {
+    runtime,
+    text,
+    source: source ?? "webhook"
+  });
+}
+async function emitHeartbeatSystemEvent(runtime, text, source) {
+  await runtime.emitEvent("HEARTBEAT_SYSTEM_EVENT", {
+    runtime,
+    text,
+    source: source ?? "webhook"
+  });
+}
+async function runIsolatedAgentTurn(runtime, params) {
+  const roomId = stringToUuid(`${runtime.agentId}-${params.sessionKey}`);
+  const existing = await runtime.getRoom(roomId);
+  if (!existing) {
+    await runtime.createRoom({
+      id: roomId,
+      name: `Hook: ${params.name}`,
+      source: "webhook",
+      type: ChannelType.GROUP,
+      channelId: params.sessionKey
+    });
+    await runtime.addParticipant(runtime.agentId, roomId);
+  }
+  const messageId = v4_default();
+  const memory = {
+    id: messageId,
+    entityId: runtime.agentId,
+    roomId,
+    agentId: runtime.agentId,
+    content: { text: `[${params.name}] ${params.message}` },
+    createdAt: Date.now()
+  };
+  let responseText = "";
+  const callback = async (response) => {
+    if (response.text) {
+      responseText += response.text;
+    }
+    return [];
+  };
+  const timeoutMs = params.timeoutSeconds ? params.timeoutSeconds * 1e3 : 3e5;
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error("Agent turn timeout")), timeoutMs);
+  });
+  await Promise.race([
+    runtime.messageService.handleMessage(runtime, memory, callback),
+    timeout
+  ]).finally(() => clearTimeout(timer));
+  return responseText;
+}
+async function handleWake(req, res, runtime) {
+  const config = resolveHooksConfig(runtime);
+  if (!config) {
+    res.status(404).json({ error: "Hooks not enabled" });
+    return;
+  }
+  if (!validateToken(req, config.token)) {
+    res.status(401).json({ error: "Unauthorized" });
+    return;
+  }
+  const body = req.body ?? {};
+  const text = typeof body.text === "string" ? body.text.trim() : "";
+  if (!text) {
+    res.status(400).json({ error: "Missing required field: text" });
+    return;
+  }
+  const mode = body.mode === "next-heartbeat" ? "next-heartbeat" : "now";
+  await emitHeartbeatSystemEvent(runtime, text, "hook:wake");
+  if (mode === "now") {
+    await emitHeartbeatWake(runtime, void 0, "hook:wake");
+  }
+  logger2.info(`[Webhooks] /hooks/wake: "${text.slice(0, 80)}" (mode: ${mode})`);
+  res.json({ ok: true });
+}
+async function handleAgent(req, res, runtime) {
+  const config = resolveHooksConfig(runtime);
+  if (!config) {
+    res.status(404).json({ error: "Hooks not enabled" });
+    return;
+  }
+  if (!validateToken(req, config.token)) {
+    res.status(401).json({ error: "Unauthorized" });
+    return;
+  }
+  const body = req.body ?? {};
+  const message = typeof body.message === "string" ? body.message.trim() : "";
+  if (!message) {
+    res.status(400).json({ error: "Missing required field: message" });
+    return;
+  }
+  const name = typeof body.name === "string" ? body.name : "Webhook";
+  const sessionKey = typeof body.sessionKey === "string" ? body.sessionKey : `hook:${v4_default()}`;
+  const wakeMode = body.wakeMode === "next-heartbeat" ? "next-heartbeat" : "now";
+  const deliver = body.deliver !== false;
+  const channel = typeof body.channel === "string" ? body.channel : "last";
+  const to = typeof body.to === "string" ? body.to : void 0;
+  const model = typeof body.model === "string" ? body.model : void 0;
+  const timeoutSeconds = typeof body.timeoutSeconds === "number" ? body.timeoutSeconds : void 0;
+  logger2.info(`[Webhooks] /hooks/agent: "${message.slice(0, 80)}" (session: ${sessionKey})`);
+  const runAsync = async () => {
+    const responseText = await runIsolatedAgentTurn(runtime, {
+      message,
+      name,
+      sessionKey,
+      model,
+      timeoutSeconds
+    });
+    if (deliver && responseText.trim() && responseText.trim() !== "HEARTBEAT_OK") {
+      await deliverToChannel(runtime, { text: responseText }, channel, to).catch(
+        (err) => {
+          logger2.warn(`[Webhooks] Delivery failed for hook agent: ${err.message}`);
+        }
+      );
+    }
+    if (responseText.trim() && responseText.trim() !== "HEARTBEAT_OK") {
+      const summary = responseText.length > 200 ? `${responseText.slice(0, 200)}\u2026` : responseText;
+      await emitHeartbeatSystemEvent(
+        runtime,
+        `[Hook "${name}" completed] ${summary}`,
+        `hook:${name}`
+      );
+    }
+    if (wakeMode === "now") {
+      await emitHeartbeatWake(runtime, void 0, `hook:${name}`);
+    }
+  };
+  runAsync().catch((err) => {
+    logger2.error(`[Webhooks] Agent hook run failed: ${err.message}`);
+  });
+  res.status(202).json({ ok: true, sessionKey });
+}
+async function handleMapped(req, res, runtime) {
+  const config = resolveHooksConfig(runtime);
+  if (!config) {
+    res.status(404).json({ error: "Hooks not enabled" });
+    return;
+  }
+  if (!validateToken(req, config.token)) {
+    res.status(401).json({ error: "Unauthorized" });
+    return;
+  }
+  const hookName = req.params?.name ?? "";
+  if (!hookName) {
+    res.status(400).json({ error: "Missing hook name" });
+    return;
+  }
+  const body = req.body ?? {};
+  const mapping = findMapping(config.mappings, hookName, body);
+  if (!mapping) {
+    res.status(404).json({ error: `No mapping found for hook: ${hookName}` });
+    return;
+  }
+  const resolved = applyMapping(mapping, hookName, body);
+  logger2.info(`[Webhooks] /hooks/${hookName}: action=${resolved.action}`);
+  if (resolved.action === "wake") {
+    await emitHeartbeatSystemEvent(runtime, resolved.text ?? "", `hook:${hookName}`);
+    if (resolved.wakeMode === "now") {
+      await emitHeartbeatWake(runtime, void 0, `hook:${hookName}`);
+    }
+    res.json({ ok: true });
+    return;
+  }
+  const runAsync = async () => {
+    const responseText = await runIsolatedAgentTurn(runtime, {
+      message: resolved.message ?? "",
+      name: resolved.name ?? hookName,
+      sessionKey: resolved.sessionKey ?? `hook:${hookName}:${Date.now()}`,
+      model: resolved.model,
+      timeoutSeconds: resolved.timeoutSeconds
+    });
+    if (resolved.deliver && responseText.trim() && responseText.trim() !== "HEARTBEAT_OK") {
+      await deliverToChannel(
+        runtime,
+        { text: responseText },
+        resolved.channel ?? "last",
+        resolved.to
+      ).catch((err) => {
+        logger2.warn(`[Webhooks] Delivery failed for mapped hook "${hookName}": ${err.message}`);
+      });
+    }
+    if (responseText.trim() && responseText.trim() !== "HEARTBEAT_OK") {
+      const summary = responseText.length > 200 ? `${responseText.slice(0, 200)}\u2026` : responseText;
+      await emitHeartbeatSystemEvent(
+        runtime,
+        `[Hook "${resolved.name ?? hookName}" completed] ${summary}`,
+        `hook:${hookName}`
+      );
+    }
+    if (resolved.wakeMode === "now") {
+      await emitHeartbeatWake(runtime, void 0, `hook:${hookName}`);
+    }
+  };
+  runAsync().catch((err) => {
+    logger2.error(`[Webhooks] Mapped hook "${hookName}" run failed: ${err.message}`);
+  });
+  res.status(202).json({ ok: true });
+}
+
+// src/index.ts
+var webhooksPlugin = {
+  name: "webhooks",
+  description: "HTTP webhook ingress for external triggers",
+  routes: [
+    {
+      type: "POST",
+      path: "/hooks/wake",
+      handler: handleWake
+    },
+    {
+      type: "POST",
+      path: "/hooks/agent",
+      handler: handleAgent
+    },
+    {
+      type: "POST",
+      path: "/hooks/:name",
+      handler: handleMapped
+    }
+  ]
+};
+var index_default = webhooksPlugin;
+export {
+  applyMapping,
+  index_default as default,
+  extractToken,
+  findMapping,
+  renderTemplate,
+  validateToken,
+  webhooksPlugin
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@elizaos/plugin-webhooks",
+  "version": "2.0.0-alpha.3",
+  "description": "HTTP webhook ingress for external triggers (wake, agent, mapped hooks)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo node_modules",
+    "lint": "bunx @biomejs/biome check --write --unsafe .",
+    "lint:check": "bunx @biomejs/biome check .",
+    "format": "bunx @biomejs/biome format --write .",
+    "format:check": "bunx @biomejs/biome format .",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@elizaos/core": "2.0.0-alpha.3"
+  },
+  "peerDependencies": {
+    "@elizaos/core": "2.0.0-alpha.3"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0",
+    "@biomejs/biome": "^2.3.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}