[release] Add webhook CRUD + signature rotation MCP tools

Wraps node-appwrite's Webhooks service. Adds list_webhooks /
get_webhook / create_webhook / update_webhook / delete_webhook /
rotate_webhook_signature to the projects tool group. Works on both
Appwrite Cloud and self-hosted.

Security: httpPass is always redacted; signatureKey is redacted except
on create_webhook and rotate_webhook_signature responses, where the
freshly-minted key is surfaced once so the caller can copy it for
downstream verification.

updateWebhook reads the current webhook to backfill name/url/events
when the patch omits any of them — the SDK requires all three on PATCH,
so this preserves true partial-update semantics from the caller's view.

Includes WebhookManager helper (mirrors ProjectsManager / FunctionManager
pattern: p-limit concurrency split, tryAwaitWithRetry on every SDK call)
and unit tests for both the redaction chokepoint and the manager's
partial-update baseline-fetch logic.

Author: ZachHandley

packages/appwrite-utils-helpers/src/projects/index.ts

@@ -1 +1,2 @@
 export * from "./projectsManager.js";
+export * from "./webhookManager.js";

packages/appwrite-utils-helpers/src/projects/webhookManager.ts

@@ -0,0 +1,219 @@
+import { Client, Webhooks, ID, type Models } from "node-appwrite";
+import pLimit from "p-limit";
+import { tryAwaitWithRetry } from "../utils/helperFunctions.js";
+
+// Mirror ProjectsManager / FunctionManager concurrency split. Webhook writes
+// are infrequent and rate-limited server-side; reads happen during MCP audits
+// where a tighter parallelism budget is acceptable.
+const webhookWriteLimit = pLimit(5);
+const webhookReadLimit = pLimit(25);
+
+export interface CreateWebhookOptions {
+  /** Custom webhook ID. Auto-generated via `ID.unique()` when omitted. */
+  webhookId?: string;
+  /** Webhook enabled flag. Default: true (Appwrite default). */
+  enabled?: boolean;
+  /** SSL/TLS certificate verification for the webhook URL. Default: true. */
+  security?: boolean;
+  /** Optional HTTP basic-auth username. Max 256 chars. */
+  httpUser?: string;
+  /** Optional HTTP basic-auth password. Max 256 chars. */
+  httpPass?: string;
+}
+
+export interface UpdateWebhookPatch {
+  /** New webhook name. Max 128 chars. */
+  name?: string;
+  /** New webhook URL. */
+  url?: string;
+  /** New events list. Max 100. */
+  events?: string[];
+  /** Enabled flag. */
+  enabled?: boolean;
+  /** SSL/TLS certificate verification. */
+  security?: boolean;
+  /** HTTP basic-auth username. */
+  httpUser?: string;
+  /** HTTP basic-auth password. */
+  httpPass?: string;
+}
+
+/**
+ * Manager wrapping the node-appwrite `Webhooks` service for project-level
+ * webhook configuration. Webhooks deliver Appwrite events (database row
+ * mutations, function invocations, auth events, etc.) to an external URL with
+ * an HMAC-signed payload.
+ *
+ * Available on both Appwrite Cloud and self-hosted — webhooks are a core
+ * project feature, not a cloud-only add-on like Backups.
+ *
+ * Concurrency: 25 for reads, 5 for writes. All SDK calls are wrapped in
+ * `tryAwaitWithRetry` for transient-error resilience.
+ *
+ * The `Webhooks` SDK service operates on the project bound to the client
+ * (set via `client.setProject(projectId)` upstream). The `projectId` arg on
+ * each method here is a documentation/sanity-check device, mirroring the
+ * `ProjectsManager` pattern.
+ */
+export class WebhookManager {
+  private client: Client;
+  private webhooks: Webhooks;
+
+  constructor(client: Client) {
+    this.client = client;
+    this.webhooks = new Webhooks(client);
+  }
+
+  /**
+   * List webhooks configured for the bound project. Supports Appwrite Query
+   * filters on: name, url, httpUser, security, events, enabled, logs, attempts.
+   */
+  public async listWebhooks(
+    projectId: string,
+    queries?: string[]
+  ): Promise<Models.WebhookList> {
+    void projectId;
+    return await webhookReadLimit(() =>
+      tryAwaitWithRetry(async () => {
+        const params: { queries?: string[] } = {};
+        if (queries && queries.length > 0) params.queries = queries;
+        return await this.webhooks.list(params);
+      })
+    );
+  }
+
+  /**
+   * Get a single webhook by ID.
+   */
+  public async getWebhook(
+    projectId: string,
+    webhookId: string
+  ): Promise<Models.Webhook> {
+    void projectId;
+    return await webhookReadLimit(() =>
+      tryAwaitWithRetry(async () =>
+        await this.webhooks.get({ webhookId })
+      )
+    );
+  }
+
+  /**
+   * Create a new webhook. If `options.webhookId` is omitted, a unique ID is
+   * generated via `ID.unique()`. Response includes the freshly-minted
+   * `signatureKey` — copy it now if you need to verify signatures, the
+   * unredacted key only flows back here and on `rotateSignature`.
+   */
+  public async createWebhook(
+    projectId: string,
+    name: string,
+    url: string,
+    events: string[],
+    options: CreateWebhookOptions = {}
+  ): Promise<Models.Webhook> {
+    void projectId;
+    const webhookId = options.webhookId ?? ID.unique();
+
+    return await webhookWriteLimit(() =>
+      tryAwaitWithRetry(async () => {
+        const params: {
+          webhookId: string;
+          url: string;
+          name: string;
+          events: string[];
+          enabled?: boolean;
+          security?: boolean;
+          httpUser?: string;
+          httpPass?: string;
+        } = { webhookId, url, name, events };
+        if (options.enabled !== undefined) params.enabled = options.enabled;
+        if (options.security !== undefined) params.security = options.security;
+        if (options.httpUser !== undefined) params.httpUser = options.httpUser;
+        if (options.httpPass !== undefined) params.httpPass = options.httpPass;
+        return await this.webhooks.create(params);
+      })
+    );
+  }
+
+  /**
+   * Update an existing webhook. The SDK requires `name`, `url`, and `events`
+   * on every update — when a patch omits any of these, the current value is
+   * read first and re-sent so the call remains a true partial update from
+   * the caller's perspective. This mirrors how the official Appwrite console
+   * sends webhook PATCHes.
+   */
+  public async updateWebhook(
+    projectId: string,
+    webhookId: string,
+    patch: UpdateWebhookPatch
+  ): Promise<Models.Webhook> {
+    void projectId;
+    return await webhookWriteLimit(() =>
+      tryAwaitWithRetry(async () => {
+        // Fetch the current shape only when the patch is incomplete — saves a
+        // round-trip for full-shape updates.
+        const needsBaseline =
+          patch.name === undefined ||
+          patch.url === undefined ||
+          patch.events === undefined;
+        const baseline = needsBaseline
+          ? await this.webhooks.get({ webhookId })
+          : null;
+
+        const params: {
+          webhookId: string;
+          name: string;
+          url: string;
+          events: string[];
+          enabled?: boolean;
+          security?: boolean;
+          httpUser?: string;
+          httpPass?: string;
+        } = {
+          webhookId,
+          name: patch.name ?? baseline!.name,
+          url: patch.url ?? baseline!.url,
+          events: patch.events ?? baseline!.events,
+        };
+        if (patch.enabled !== undefined) params.enabled = patch.enabled;
+        if (patch.security !== undefined) params.security = patch.security;
+        if (patch.httpUser !== undefined) params.httpUser = patch.httpUser;
+        if (patch.httpPass !== undefined) params.httpPass = patch.httpPass;
+        return await this.webhooks.update(params);
+      })
+    );
+  }
+
+  /**
+   * Delete a webhook by ID. The Appwrite project stops emitting events to
+   * the URL immediately.
+   */
+  public async deleteWebhook(
+    projectId: string,
+    webhookId: string
+  ): Promise<void> {
+    void projectId;
+    await webhookWriteLimit(() =>
+      tryAwaitWithRetry(async () => {
+        await this.webhooks.delete({ webhookId });
+      })
+    );
+  }
+
+  /**
+   * Rotate the webhook signature key. The new key is returned in the
+   * response (`signatureKey` field) — copy it immediately and update any
+   * downstream signature verification, the unredacted key only flows back
+   * here and on the initial `createWebhook` call.
+   */
+  public async rotateSignature(
+    projectId: string,
+    webhookId: string
+  ): Promise<Models.Webhook> {
+    void projectId;
+    return await webhookWriteLimit(() =>
+      tryAwaitWithRetry(async () =>
+        await this.webhooks.updateSignature({ webhookId })
+      )
+    );
+  }
+}

packages/appwrite-utils-helpers/tests/webhookManager.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, test } from "bun:test";
+import { Client, type Models } from "node-appwrite";
+
+import { WebhookManager } from "../src/projects/webhookManager.js";
+
+/**
+ * Build a WebhookManager backed by a fake `Webhooks` SDK stub. We construct
+ * the real manager (so concurrency limiters + retry wrapping are exercised)
+ * then replace its private `.webhooks` slot with a stub that records calls.
+ */
+function buildManagerWithStub() {
+  const client = new Client();
+  const manager = new WebhookManager(client);
+
+  const calls: Array<{ method: string; args: unknown }> = [];
+  let nextGetResult: Partial<Models.Webhook> | null = null;
+
+  const stub = {
+    async list(params: { queries?: string[] }): Promise<Models.WebhookList> {
+      calls.push({ method: "list", args: params });
+      return { total: 0, webhooks: [] };
+    },
+    async get(params: { webhookId: string }): Promise<Models.Webhook> {
+      calls.push({ method: "get", args: params });
+      return {
+        $id: params.webhookId,
+        $createdAt: "now",
+        $updatedAt: "now",
+        name: nextGetResult?.name ?? "Baseline name",
+        url: nextGetResult?.url ?? "https://baseline.test/hook",
+        events: nextGetResult?.events ?? ["baseline.event"],
+        security: nextGetResult?.security ?? true,
+        httpUser: nextGetResult?.httpUser ?? "",
+        httpPass: nextGetResult?.httpPass ?? "",
+        signatureKey: nextGetResult?.signatureKey ?? "sk-baseline",
+        enabled: nextGetResult?.enabled ?? true,
+        logs: "",
+        attempts: 0,
+      } as Models.Webhook;
+    },
+    async create(params: unknown): Promise<Models.Webhook> {
+      calls.push({ method: "create", args: params });
+      return { $id: "wh-new" } as Models.Webhook;
+    },
+    async update(params: unknown): Promise<Models.Webhook> {
+      calls.push({ method: "update", args: params });
+      return { $id: "wh-updated" } as Models.Webhook;
+    },
+    async delete(params: unknown): Promise<Record<string, never>> {
+      calls.push({ method: "delete", args: params });
+      return {};
+    },
+    async updateSignature(params: unknown): Promise<Models.Webhook> {
+      calls.push({ method: "updateSignature", args: params });
+      return { $id: "wh-rotated", signatureKey: "sk-rotated" } as Models.Webhook;
+    },
+  };
+
+  (manager as unknown as { webhooks: typeof stub }).webhooks = stub;
+
+  return {
+    manager,
+    calls,
+    setNextGetResult(w: Partial<Models.Webhook> | null) {
+      nextGetResult = w;
+    },
+  };
+}
+
+describe("WebhookManager", () => {
+  test("listWebhooks omits empty queries from the SDK params", async () => {
+    const { manager, calls } = buildManagerWithStub();
+    await manager.listWebhooks("proj-1");
+    expect(calls[0]?.args).toEqual({});
+  });
+
+  test("listWebhooks forwards non-empty queries", async () => {
+    const { manager, calls } = buildManagerWithStub();
+    await manager.listWebhooks("proj-1", ['equal("enabled",true)']);
+    expect(calls[0]?.args).toEqual({ queries: ['equal("enabled",true)'] });
+  });
+
+  test("createWebhook generates a unique webhookId when not provided", async () => {
+    const { manager, calls } = buildManagerWithStub();
+    await manager.createWebhook("proj-1", "n", "https://a.test/h", ["x.y"]);
+    const args = calls[0]?.args as { webhookId?: string };
+    expect(typeof args.webhookId).toBe("string");
+    expect(args.webhookId!.length).toBeGreaterThan(0);
+  });
+
+  test("createWebhook honors an explicit webhookId", async () => {
+    const { manager, calls } = buildManagerWithStub();
+    await manager.createWebhook("proj-1", "n", "https://a.test/h", ["x.y"], {
+      webhookId: "my-id",
+    });
+    expect((calls[0]?.args as { webhookId: string }).webhookId).toBe("my-id");
+  });
+
+  test("createWebhook only forwards options that were actually set", async () => {
+    const { manager, calls } = buildManagerWithStub();
+    await manager.createWebhook("proj-1", "n", "https://a.test/h", ["x.y"], {
+      enabled: true,
+    });
+    const args = calls[0]?.args as Record<string, unknown>;
+    expect(args.enabled).toBe(true);
+    expect("security" in args).toBe(false);
+    expect("httpUser" in args).toBe(false);
+    expect("httpPass" in args).toBe(false);
+  });
+
+  test("updateWebhook with a partial patch first reads baseline then sends a full PUT", async () => {
+    // The SDK requires name/url/events on every PATCH; the manager must
+    // backfill from a fresh get() when the caller omits any of them.
+    const { manager, calls, setNextGetResult } = buildManagerWithStub();
+    setNextGetResult({
+      name: "Old name",
+      url: "https://old.test/hook",
+      events: ["a.b", "c.d"],
+    });
+    await manager.updateWebhook("proj-1", "wh-1", { enabled: false });
+
+    expect(calls[0]?.method).toBe("get");
+    expect(calls[1]?.method).toBe("update");
+    const upd = calls[1]?.args as {
+      name: string;
+      url: string;
+      events: string[];
+      enabled: boolean;
+    };
+    expect(upd.name).toBe("Old name");
+    expect(upd.url).toBe("https://old.test/hook");
+    expect(upd.events).toEqual(["a.b", "c.d"]);
+    expect(upd.enabled).toBe(false);
+  });
+
+  test("updateWebhook with a full patch skips the baseline GET", async () => {
+    const { manager, calls } = buildManagerWithStub();
+    await manager.updateWebhook("proj-1", "wh-1", {
+      name: "New",
+      url: "https://new.test/hook",
+      events: ["fresh.event"],
+      enabled: true,
+    });
+    expect(calls.map((c) => c.method)).toEqual(["update"]);
+  });
+
+  test("rotateSignature returns the new signatureKey for the caller to copy", async () => {
+    const { manager } = buildManagerWithStub();
+    const res = await manager.rotateSignature("proj-1", "wh-1");
+    expect(res.signatureKey).toBe("sk-rotated");
+  });
+
+  test("deleteWebhook returns void after a successful call", async () => {
+    const { manager, calls } = buildManagerWithStub();
+    await manager.deleteWebhook("proj-1", "wh-1");
+    expect(calls[0]?.method).toBe("delete");
+    expect((calls[0]?.args as { webhookId: string }).webhookId).toBe("wh-1");
+  });
+});