@antasphere/chassis-server 1.0.2 → 1.2.0

package/src/env.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { parseApiKeyPeppers } from './apikeys/peppers.js';
 import { parseSuperadminEmails } from './accounts/superadmin.js';
 import { isDemoSignInHost, parseDemoEmailDomains, parseDemoHosts } from './identity/demo-pass-rules.js';
+import { loadCliPackage } from './cli-package/index.js';
 
 /**
  * The single entry point for configuration. Every env var the app reads is
@@ -198,6 +199,19 @@ const chassisEnvShape = (version: string) => ({
   HUB_HINT_COOKIE_DOMAIN: optionalString(z.string().min(1)),
   /** The restricted bit on the tool itself (PRDCT-2947): `true` on the cloud edition makes this instance refuse to create an organization (`POST /workspaces` answers 403 `restricted_tool`, `/me.canCreateWorkspace` is false) and advertise `restricted: true` in discovery, so a tool that Antasphere opens to organizations one by one does not rest on the hub registry's flag alone. No effect on the self-hosted edition, where workspaces are local. */
   TOOL_RESTRICTED: booleanish.default(false),
+  /** The tool's own CLI package as the release packed it (PRDCT-3312): a folder holding `package.tgz` (the output of `pnpm pack` of `packages/cli`) beside a copy of that package's `package.json`. The image sets it. Cloud edition: the instance serves the tarball on `POST /cli/package` to a member the hub lets into the tool, and discovery carries `cli { name, version }` so the `team` command knows what it installs and whether to update. Unset = the instance serves no CLI: discovery carries no `cli` and the route answers 404 `cli_not_packaged`. A set value whose folder does not hold both files, or whose `package.json` has no string `name` and `version`, refuses the boot with the path and what is missing: a misconfiguration is proven at the image, never discovered by a person's install. */
+  CLI_PACKAGE_DIR: optionalString(
+    z
+      .string()
+      .min(1)
+      .superRefine((dir, ctx) => {
+        try {
+          loadCliPackage(dir);
+        } catch (err) {
+          ctx.addIssue({ code: 'custom', message: err instanceof Error ? err.message : String(err) });
+        }
+      })
+  ),
   /** R7 escape hatch (internal/federation.md): acknowledge an EDITION change on an already-set-up instance. Without it, boot refuses an EDITION that differs from the one stamped at setup — flipping editions under existing users/workspaces changes identity semantics and must be a conscious operator act. */
   EDITION_CHANGE_ALLOWED: booleanish.default(false),
   /** Reported version. Defaults to the code's own baked-in package version (PRDCT-1844) — the image knows its version intrinsically, CI injects nothing. The env var remains as a deliberate operator override only. */
@@ -252,6 +266,10 @@ const chassisEnvShape = (version: string) => ({
   METRICS_TOKEN: optionalString(z.string().min(8)),
   /** Days of audit_log to keep (nightly purge at 03:00). 0 = keep forever. */
   AUDIT_RETENTION_DAYS: numeric(z.coerce.number().int().min(0).default(365)),
+  /** Days of webhook deliveries (the per-endpoint log) to keep (nightly purge at 03:00). 0 = keep forever. */
+  WEBHOOK_DELIVERY_RETENTION_DAYS: numeric(z.coerce.number().int().min(0).default(30)),
+  /** Let webhook endpoints target private, loopback and link-local addresses (a self-hoster's own n8n on the LAN). Default false: a webhook never reaches the instance's own network. Refused on EDITION=cloud. */
+  WEBHOOKS_ALLOW_PRIVATE_NETWORKS: booleanish.default(false),
   /** Grace period for orphaned users (accounts with ZERO workspace memberships, e.g. setup-race losers): the nightly 03:00 sweep deletes them once older than this many hours. A user with ANY membership row — even deactivated — is never touched. 0 = sweep disabled. */
   ORPHAN_USER_RETENTION_HOURS: numeric(z.coerce.number().int().min(0).default(72)),
   /** pino level. */
@@ -358,6 +376,13 @@ export function buildEnvSchema<TShape extends z.ZodRawShape = {}>(
     extension?.refine?.(env, ctx);
     demoSignInRefusal(env, ctx);
     if (env.EDITION !== 'cloud') return;
+    if (env.WEBHOOKS_ALLOW_PRIVATE_NETWORKS) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['WEBHOOKS_ALLOW_PRIVATE_NETWORKS'],
+        message: 'never on EDITION=cloud: a webhook of the cloud edition reaches public addresses only'
+      });
+    }
     for (const key of HUB_REQUIRED_VARS) {
       if (env[key] === undefined) {
         ctx.addIssue({

package/src/identity/demo-pass-rules.ts

@@ -220,7 +220,12 @@ export const DEMO_SESSION_REFUSED_API_ROUTES: readonly DemoSessionRefusedApiRout
   { method: 'ALL', path: '/demo/passes', does: 'manage demo links' },
   { method: 'ALL', path: '/demo/passes/*', does: 'manage demo links' },
   { method: 'POST', path: '/workspaces', does: 'create a workspace' },
-  { method: 'PUT', path: '/me/default-workspace', does: 'change your default workspace' }
+  { method: 'PUT', path: '/me/default-workspace', does: 'change your default workspace' },
+  // A webhook is something the workspace keeps, and its secret is a credential (PRDCT-3482).
+  { method: 'POST', path: '/webhooks', does: 'register a webhook' },
+  { method: 'PATCH', path: '/webhooks/*', does: 'change a webhook' },
+  { method: 'DELETE', path: '/webhooks/*', does: 'delete a webhook' },
+  { method: 'POST', path: '/webhooks/*', does: 'act on a webhook' }
 ];
 
 /** The refusal's sentence for one entry of `DEMO_SESSION_REFUSED_API_ROUTES`. */

package/src/identity/hub-reconcile.ts

@@ -3,7 +3,7 @@ import { and, eq, inArray, isNotNull, ne, notInArray, sql } from 'drizzle-orm';
 import { workspaceMembers, workspaces, type Db } from '@antasphere/chassis-db';
 import type { AuditService } from '../audit/service.js';
 import type { Logger } from '../logger.js';
-import { deleteMembershipGrants, type MembershipRemovalHook } from '../members/removal.js';
+import { deleteMembershipGrants, type BoundMembershipRemoval } from '../members/removal.js';
 import { projectOrgMembership, projectOrgTeams, projectTeamSeats } from './hub-projection.js';
 import type { HubDeniedOrg, HubUserClient, LoginAccessToken } from './hub-user-client.js';
 
@@ -130,7 +130,7 @@ export interface HubOrgReconcilerDeps {
   logger: Logger;
   dials: HubFederationDials;
   /** The tool's half of a removal (the `membershipRemoval` slot), run in the sweep's transaction. */
-  onMembershipRemoval?: MembershipRemovalHook | undefined;
+  onMembershipRemoval?: BoundMembershipRemoval | undefined;
   /** Test seam. */
   now?: () => number;
 }

package/src/index.ts

@@ -62,4 +62,16 @@ export function createPlatform<
 ): Platform<TEnvShape, TDomain, TEvents, TToolOverrides> {
   return { boot: (source, overrides) => bootPlatform(tool, source, overrides) };
 }
-export type { MembershipRemovalHook, RemovedMembership, RemovalCounts } from './members/removal.js';
+export type {
+  MembershipRemovalContext,
+  MembershipRemovalHook,
+  RemovedMembership,
+  RemovalCounts
+} from './members/removal.js';
+export type {
+  WebhookCatalogDeclaration,
+  WebhookEmitter,
+  WebhookEventDeclaration,
+  WebhookSubjectDeclaration,
+  WebhookSubjectValue
+} from './webhooks/index.js';

package/src/jobs/index.ts

@@ -1,5 +1,6 @@
 export {
   type JobDeclaration,
+  type QueueOptions,
   type Jobs,
   type UsageRetry,
   DEFAULT_USAGE_RETRY,

package/src/jobs/pgboss.ts

@@ -69,9 +69,55 @@ export const ORPHAN_USER_PURGE_QUEUE = 'orphan-user-purge';
 export interface JobDeclaration<TData extends object = object> {
   queue: string;
   schedule?: { cron: string; enabled?: boolean };
+  /**
+   * The queue's own settings (PRDCT-3482), applied at install on every
+   * worker boot: the retry budget of the jobs sent to it and its dead
+   * letter, the queue a job goes to when the budget runs out. The dead
+   * letter is named ON THE QUEUE, never on a send (pg-boss stamps it on
+   * each job row at insert, and an api-role replica sends with no DDL), so
+   * it must be declared BEFORE the queue that names it.
+   */
+  options?: QueueOptions;
+  /**
+   * How many pollers this replica runs on the queue (default 1). pg-boss's
+   * worker is a serial loop, one job at a time; a queue whose handler waits
+   * on the outside (a webhook delivery, up to its timeout) declares more, so
+   * one silent receiver never holds every other job of the instance behind
+   * it (verifier round 1, MJ1). Each poller fetches with SKIP LOCKED, so the
+   * pollers never share a job.
+   */
+  concurrency?: number;
+  /**
+   * How often each poller asks for work, in seconds (pg-boss's default is
+   * two). pg-boss's worker sleeps this long after EVERY loop, jobs found or
+   * not, so a queue that must drain a burst declares a short one (verifier
+   * round 2, MJ-R2-1).
+   */
+  pollingIntervalSeconds?: number;
   handler(data: TData | null, job: TimerJob): Promise<void>;
 }
 
+/** A queue's settings, as a declaration names them. */
+export interface QueueOptions {
+  retryLimit?: number;
+  retryDelaySeconds?: number;
+  retryBackoff?: boolean;
+  /** The queue a job moves to when its retries run out; declared earlier in the list. */
+  deadLetter?: string;
+  expireInSeconds?: number;
+}
+
+function pgBossQueueOptions(name: string, options: QueueOptions): PgBoss.Queue {
+  return {
+    name,
+    ...(options.retryLimit !== undefined ? { retryLimit: options.retryLimit } : {}),
+    ...(options.retryDelaySeconds !== undefined ? { retryDelay: options.retryDelaySeconds } : {}),
+    ...(options.retryBackoff !== undefined ? { retryBackoff: options.retryBackoff } : {}),
+    ...(options.deadLetter !== undefined ? { deadLetter: options.deadLetter } : {}),
+    ...(options.expireInSeconds !== undefined ? { expireInSeconds: options.expireInSeconds } : {})
+  };
+}
+
 /**
  * Advisory-lock key serializing pg-boss's install DDL across replicas.
  *
@@ -219,6 +265,10 @@ export async function createJobs(
       // The tool's queues: same install section, same lock, declaration order.
       for (const job of toolJobs) {
         await boss.createQueue(job.queue);
+        // The settings are applied on every boot (`createQueue` leaves an
+        // existing queue as it is), so a changed budget reaches an installed
+        // instance at its next worker boot.
+        if (job.options) await boss.updateQueue(job.queue, pgBossQueueOptions(job.queue, job.options));
         if (!job.schedule) continue;
         if (job.schedule.enabled !== false) {
           await boss.schedule(job.queue, job.schedule.cron);
@@ -372,15 +422,27 @@ export async function createJobs(
     // default batch), its payload and its key handed to the handler: a timer
     // (`./timers.ts`) rides the same poller as a cron.
     for (const job of toolJobs) {
-      await boss.work<object>(job.queue, { includeMetadata: true }, async (jobs) => {
-        for (const fetched of jobs) {
-          await job.handler(fetched.data ?? null, {
-            id: fetched.id,
-            queue: job.queue,
-            key: fetched.singletonKey ?? null
-          });
-        }
-      });
+      const pollers = Math.max(1, Math.floor(job.concurrency ?? 1));
+      for (let i = 0; i < pollers; i++) {
+        await boss.work<object>(
+          job.queue,
+          {
+            includeMetadata: true,
+            ...(job.pollingIntervalSeconds !== undefined
+              ? { pollingIntervalSeconds: job.pollingIntervalSeconds }
+              : {})
+          },
+          async (jobs) => {
+            for (const fetched of jobs) {
+              await job.handler(fetched.data ?? null, {
+                id: fetched.id,
+                queue: job.queue,
+                key: fetched.singletonKey ?? null
+              });
+            }
+          }
+        );
+      }
     }
 
     // Orphaned-user GC: setup-race losers, fail-closed SSO login strands

package/src/mcp/index.ts

@@ -10,6 +10,7 @@ export {
 export { mcpRoutes } from './http.js';
 export { projectErrorHints, registerProjectTools } from './projects.js';
 export { registerTeamTools } from './teams.js';
+export { registerWebhookTools, webhookErrorHints } from './webhooks.js';
 export { type McpInputs, mcpInputs } from './inputs.js';
 export {
   type McpIdentity,

package/src/mcp/server.ts

@@ -4,6 +4,7 @@ import { mcpInputs } from './inputs.js';
 import { jsonText, mergeErrorHints, wrapToolErrors, type ErrorHints } from './errors.js';
 import { projectErrorHints, registerProjectTools } from './projects.js';
 import { registerTeamTools } from './teams.js';
+import { registerWebhookTools, webhookErrorHints } from './webhooks.js';
 import {
   callApi,
   createScopeCheck,
@@ -57,13 +58,17 @@ export type McpIdentity = ToolIdentity['mcp'];
 
 /**
  * The ONE composition of an instance's hint table: the domain hints, then
- * every chassis group (the projects today), then the tool's own last, so a
+ * every chassis group (the projects, the webhooks), then the tool's own last, so a
  * tool may re-word a chassis code and never the reverse. A tool set that
  * wraps its own errors reads the same composition (never a copy), so a
  * chassis group added here reaches the tool's tools without a second edit.
  */
 export function composeErrorHints(toolHints: ErrorHints, toolPrefix: string): ErrorHints {
-  return mergeErrorHints({ ...projectErrorHints(toolPrefix), ...toolHints });
+  return mergeErrorHints({
+    ...projectErrorHints(toolPrefix),
+    ...webhookErrorHints(toolPrefix),
+    ...toolHints
+  });
 }
 
 export function buildMcpServer(
@@ -166,6 +171,9 @@ export function buildMcpServer(
   // Teams (PRDCT-2813): a chassis concept too, read-only over MCP, right after
   // the projects they can be members of.
   registerTeamTools(server, ctx, identity, tool.scopes, checkScope, hints);
+  // Webhooks (PRDCT-3482): a chassis concept, registered only when the tool
+  // declares the webhooks scope (a tool without one serves no webhook tool).
+  if (tool.scopes.webhooks) registerWebhookTools(server, ctx, identity, tool.scopes, checkScope, hints);
 
   // The product surface: the tool's own set, after the chassis tools.
   tool.registerTools(server, ctx);

package/src/mcp/tool-kit.ts

@@ -62,6 +62,8 @@ export type ScopeCheck<TScope extends string> = (
 export interface McpScopes<TRead extends string = string, TWrite extends string = string> {
   read: TRead;
   write: TWrite;
+  /** The webhooks' opt-in scope (PRDCT-3482); absent, the chassis registers no webhook tool. */
+  webhooks?: string | undefined;
 }
 
 export function createScopeCheck<TRead extends string, TWrite extends string>(
@@ -71,7 +73,11 @@ export function createScopeCheck<TRead extends string, TWrite extends string>(
     if (principal.scopes && !principal.scopes.has(scope)) {
       return deny(
         `Missing scope "${scope}": this connection was not granted ` +
-          (scope === scopes.write ? 'permission to create or edit data.' : 'permission to read data.') +
+          (scope === scopes.write
+            ? 'permission to create or edit data.'
+            : scope === scopes.webhooks
+              ? 'permission to manage webhooks.'
+              : 'permission to read data.') +
           ' Reconnect the MCP server and approve the permission on the consent screen.'
       );
     }

package/src/mcp/webhooks.ts

@@ -0,0 +1,370 @@
+import { z } from 'zod';
+import {
+  webhookDeliveryStatusSchema,
+  webhookEventPatternSchema,
+  webhookFiltersSchema,
+  webhookUrlSchema
+} from '@antasphere/chassis-contract';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { mcpInputs } from './inputs.js';
+import { deny, jsonText, wrapToolErrors, type ErrorHints, type ToolTextResult } from './errors.js';
+import {
+  callApi,
+  forWorkspace,
+  pageQuery,
+  type McpScopes,
+  type McpToolContext,
+  type ScopeCheck
+} from './tool-kit.js';
+import type { McpIdentity } from './server.js';
+
+/**
+ * The eleven WEBHOOK tools (PRDCT-3482), registered by the chassis right after
+ * the team reads and only when the tool declares a webhooks scope: a webhook
+ * is a chassis concept (a URL a workspace registers to be told, by a signed
+ * POST, when one of the tool's events happens), so the tools over it are the
+ * chassis'. Thin shims over the instance's own /api/v1/webhooks called
+ * IN-PROCESS with the caller's bearer forwarded verbatim: the API's
+ * fail-closed scope allowlist, its owner-or-admin rule and its 404 for an
+ * endpoint of another workspace apply unchanged.
+ *
+ * Every tool pre-checks the tool's webhooks scope, except the catalog, which
+ * is a read (every non-guest member's, under the read scope). Nothing here
+ * names a tool, a brand or a domain: the prefix arrives as
+ * `identity.toolPrefix`, the event types as the instance's catalog.
+ */
+
+/** What a webhook IS, opening the descriptions. */
+const WHAT_IS_A_WEBHOOK =
+  'A webhook is a URL an organization registers to be told, by a signed HTTP POST, when something ' +
+  'happens (for example `thing.created`).';
+
+/** Who manages them. */
+const WHO_MANAGES = 'Only an owner or an admin of the organization manages webhooks, reads included.';
+
+/** How the `events` list of an endpoint reads. */
+const EVENT_PATTERNS =
+  'Each entry of `events` is an exact event type (`thing.created`), a family (`thing.*`) or ' +
+  'everything (`*`).';
+
+/**
+ * The webhook code only the webhook routes answer, merged into the instance's
+ * hint table by `composeErrorHints` like the project hints. The codes the
+ * webhook routes SHARE with the rest of the instance (`forbidden`,
+ * `demo_session`, `plan_required`) are worded for webhooks on the webhook
+ * tools alone ({@link webhookToolHints}): in the instance's table they would
+ * misread every other route's refusal.
+ */
+export function webhookErrorHints(toolPrefix: string): ErrorHints {
+  return {
+    url_refused:
+      'This instance does not deliver to that address. Refused: a scheme other than http or https ' +
+      '(https only on the cloud), a URL carrying a user name or password, a port other than the ' +
+      'scheme’s default, and an address that is not on the public internet (localhost, a private or ' +
+      'link-local network), unless the operator of a self-hosted instance opened private networks. ' +
+      `Use a public address of the receiver, then call ${toolPrefix}create_webhook or ` +
+      `${toolPrefix}update_webhook again.`,
+    unknown_event:
+      'One of the `events` entries is not an event type or family this instance delivers. ' +
+      `Read ${toolPrefix}webhook_events for the exact types; a family is its first word plus \`.*\`.`,
+    unknown_subject:
+      'One of the `filters` keys is not a subject this instance declares. ' +
+      `The subject keys are in ${toolPrefix}webhook_events (for example \`project\`).`
+  };
+}
+
+/** The shared codes, worded for the webhook tools only (layered over the instance's table there). */
+function webhookToolHints(toolPrefix: string): ErrorHints {
+  return {
+    forbidden:
+      'Only an owner or an admin of the organization manages webhooks, reads included. Ask one of ' +
+      `them to make the change, or to read the endpoints (${toolPrefix}webhook_events stays open to ` +
+      'every member).',
+    demo_session:
+      'This connection was opened by a demonstration link, which may not set up webhooks. A person ' +
+      'signed in with their own account must do it.',
+    plan_required:
+      'The organization’s plan does not include this — the upgrade link in this message is where a ' +
+      'human raises it; nothing was created.'
+  };
+}
+
+const webhookIdInput = z
+  .uuid()
+  .describe('The webhook id, from the webhook list or the create answer (never its URL).');
+
+const deliveryIdInput = z.uuid().describe('The delivery id, from the delivery list of this webhook.');
+
+const urlInput = webhookUrlSchema.describe(
+  'Where the deliveries go: a public http or https URL without credentials (https only on the cloud).'
+);
+
+const eventsInput = z
+  .array(webhookEventPatternSchema)
+  .min(1)
+  .max(50)
+  .describe(`What the endpoint subscribes to. ${EVENT_PATTERNS}`);
+
+const descriptionInput = z.string().max(200).describe('A short note on what the endpoint is for.');
+
+const filtersInput = webhookFiltersSchema.describe(
+  'Narrows the subscription by subject: a subject key of the catalog (its `subjects[].key`) mapped to ' +
+    'the ids it accepts, AND across keys, OR within a key; an event that does not carry a filtered ' +
+    'subject does not match. An empty object filters nothing.'
+);
+
+const enabledInput = z.boolean().describe('false pauses the deliveries without deleting the endpoint.');
+
+/** Register the eleven webhook tools on a server, after the team reads. */
+export function registerWebhookTools(
+  server: McpServer,
+  ctx: McpToolContext,
+  identity: McpIdentity,
+  scopes: McpScopes,
+  checkScope: ScopeCheck<string>,
+  hints: ErrorHints
+): void {
+  const webhooksScope = scopes.webhooks;
+  if (!webhooksScope) return;
+  const { workspaceInput, cursorInput, limitInput } = mcpInputs(identity);
+  const prefix = identity.toolPrefix;
+  const t = (name: string) => `${prefix}${name}`;
+  const toolHints: ErrorHints = { ...hints, ...webhookToolHints(prefix) };
+
+  const run = (
+    scope: string,
+    workspace: string | undefined,
+    body: (c: McpToolContext) => Promise<unknown>
+  ): Promise<ToolTextResult> => {
+    const denied = checkScope(ctx.principal, scope);
+    if (denied) return Promise.resolve(denied);
+    const c = forWorkspace(ctx, workspace);
+    return wrapToolErrors(async () => jsonText(await body(c)), toolHints);
+  };
+
+  const send = (method: string, value?: unknown): RequestInit =>
+    value === undefined
+      ? { method }
+      : { method, headers: { 'content-type': 'application/json' }, body: JSON.stringify(value) };
+
+  const base = '/api/v1/webhooks';
+
+  // ── The catalog: a read ──────────────────────────────────────────────────
+
+  server.registerTool(
+    t('webhook_events'),
+    {
+      description:
+        `The event catalog of this instance: every event type it delivers to webhooks. ${WHAT_IS_A_WEBHOOK} ` +
+        'Returns { subjects: [{ key, field, description }], events: [{ type, description, subjects, ' +
+        'schema }] } — `subjects` are what an event is about (the key a filter uses, and the field of ' +
+        'the envelope’s `subjects` its value is written under: one id or a list of ids), `schema` is ' +
+        'the JSON Schema of the event’s `data`. ' +
+        `${EVENT_PATTERNS} Read this before ${t('create_webhook')}. Every member may read it.`,
+      inputSchema: { workspace: workspaceInput },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace }) => run(scopes.read, workspace, (c) => callApi(c, `${base}/events`))
+  );
+
+  // ── Endpoints ────────────────────────────────────────────────────────────
+
+  server.registerTool(
+    t('list_webhooks'),
+    {
+      description:
+        `List the organization’s webhooks, newest first. ${WHAT_IS_A_WEBHOOK} ${WHO_MANAGES} Returns ` +
+        '{ webhooks: [{ id, url, description, events, filters, enabled, createdBy, createdAt, ' +
+        'updatedAt, disabledAt, disabledReason, consecutiveFailures, lastDeliveryAt, ' +
+        'lastDeliveryStatus, previousSecretExpiresAt }], nextCursor } — never a signing secret. ' +
+        '`disabledAt` is set when the instance switched the endpoint off after failing too long. When ' +
+        'nextCursor is non-null, call again with cursor set to it.',
+      inputSchema: { workspace: workspaceInput, limit: limitInput, cursor: cursorInput },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace, limit, cursor }) =>
+      run(webhooksScope, workspace, (c) => callApi(c, pageQuery(base, { cursor, limit })))
+  );
+
+  server.registerTool(
+    t('create_webhook'),
+    {
+      description:
+        `Register a webhook — confirm with the user first (URL and events included). ${WHAT_IS_A_WEBHOOK} ` +
+        `${WHO_MANAGES} ${EVENT_PATTERNS} The types are checked against ${t('webhook_events')}, and ` +
+        'the keys of `filters` are the catalog’s subject keys. The answer is the endpoint plus its ' +
+        'signing `secret` (`whsec_…`), shown ONCE and never again: give it to the receiver, which ' +
+        'verifies every delivery’s Standard Webhooks signature with it, and never store it anywhere ' +
+        `else. A lost secret is replaced by ${t('rotate_webhook_secret')}.`,
+      inputSchema: {
+        workspace: workspaceInput,
+        url: urlInput,
+        events: eventsInput,
+        description: descriptionInput.optional(),
+        filters: filtersInput.optional(),
+        enabled: enabledInput.optional()
+      }
+    },
+    async ({ workspace, url, events, description, filters, enabled }) =>
+      run(webhooksScope, workspace, (c) =>
+        callApi(
+          c,
+          base,
+          send('POST', {
+            url,
+            events,
+            ...(description !== undefined ? { description } : {}),
+            ...(filters !== undefined ? { filters } : {}),
+            ...(enabled !== undefined ? { enabled } : {})
+          })
+        )
+      )
+  );
+
+  server.registerTool(
+    t('get_webhook'),
+    {
+      description:
+        `Read one webhook, without its secret. ${WHO_MANAGES} Returns the endpoint as ` +
+        `${t('list_webhooks')} shows it. A webhook of another organization answers not found.`,
+      inputSchema: { workspace: workspaceInput, webhookId: webhookIdInput },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace, webhookId }) =>
+      run(webhooksScope, workspace, (c) => callApi(c, `${base}/${webhookId}`))
+  );
+
+  server.registerTool(
+    t('update_webhook'),
+    {
+      description:
+        'Change a webhook’s URL, description, events, filters or enabled switch — confirm with the ' +
+        `user first. ${WHO_MANAGES} Send only the fields you are changing; \`events\` and \`filters\` ` +
+        `REPLACE the whole list or object. ${EVENT_PATTERNS} Setting enabled back to true resumes an ` +
+        'endpoint the instance switched off. The secret is unchanged. Returns the endpoint as it now is.',
+      inputSchema: {
+        workspace: workspaceInput,
+        webhookId: webhookIdInput,
+        url: urlInput.optional(),
+        description: descriptionInput.optional(),
+        events: eventsInput.optional(),
+        filters: filtersInput.optional(),
+        enabled: enabledInput.optional()
+      }
+    },
+    async ({ workspace, webhookId, url, description, events, filters, enabled }) => {
+      const patch = { url, description, events, filters, enabled };
+      if (Object.values(patch).every((v) => v === undefined)) {
+        return deny(
+          'Nothing to change: pass at least one of url, description, events, filters or enabled. ' +
+            `Read the webhook first (${t('get_webhook')}) if you need its current values.`
+        );
+      }
+      const body = Object.fromEntries(Object.entries(patch).filter(([, v]) => v !== undefined));
+      return run(webhooksScope, workspace, (c) => callApi(c, `${base}/${webhookId}`, send('PATCH', body)));
+    }
+  );
+
+  server.registerTool(
+    t('delete_webhook'),
+    {
+      description:
+        'Delete a webhook and its whole delivery history — confirm with the user first; nothing more ' +
+        `is sent to it and this cannot be undone. ${WHO_MANAGES} To pause it instead, call ` +
+        `${t('update_webhook')} with enabled set to false. Returns a last snapshot of the deleted endpoint.`,
+      inputSchema: { workspace: workspaceInput, webhookId: webhookIdInput },
+      annotations: { destructiveHint: true }
+    },
+    async ({ workspace, webhookId }) =>
+      run(webhooksScope, workspace, (c) => callApi(c, `${base}/${webhookId}`, send('DELETE')))
+  );
+
+  server.registerTool(
+    t('rotate_webhook_secret'),
+    {
+      description:
+        'Replace a webhook’s signing secret — confirm with the user first. ' +
+        `${WHO_MANAGES} The answer is the endpoint plus its new \`secret\` (\`whsec_…\`), shown ONCE: ` +
+        'give it to the receiver and never store it anywhere else. The previous secret keeps signing ' +
+        'until `previousSecretExpiresAt`, so the receiver can switch without a gap.',
+      inputSchema: { workspace: workspaceInput, webhookId: webhookIdInput }
+    },
+    async ({ workspace, webhookId }) =>
+      run(webhooksScope, workspace, (c) => callApi(c, `${base}/${webhookId}/rotate-secret`, send('POST')))
+  );
+
+  server.registerTool(
+    t('test_webhook'),
+    {
+      description:
+        'Send a signed `webhook.ping` to a webhook now, once, and answer how it went. ' +
+        `${WHO_MANAGES} Returns { delivery: { id, eventId, eventType, status, attempt, ` +
+        'lastStatusCode, lastError, … } } — `status` is `delivered` when the receiver answered 2xx, ' +
+        '`failed` otherwise, with `lastStatusCode` and `lastError` saying why. A ping is never retried.',
+      inputSchema: { workspace: workspaceInput, webhookId: webhookIdInput }
+    },
+    async ({ workspace, webhookId }) =>
+      run(webhooksScope, workspace, (c) => callApi(c, `${base}/${webhookId}/test`, send('POST')))
+  );
+
+  // ── Deliveries ───────────────────────────────────────────────────────────
+
+  server.registerTool(
+    t('list_webhook_deliveries'),
+    {
+      description:
+        `List a webhook’s deliveries, newest first, optionally by status. ${WHO_MANAGES} A delivery ` +
+        'is one event sent to this endpoint, with its attempts. Returns { deliveries: [{ id, ' +
+        'endpointId, eventId, eventType, status, attempt, lastStatusCode, lastError, nextAttemptAt, ' +
+        'deliveredAt, createdAt, updatedAt, payload }], nextCursor } — `eventId` is the receiver’s ' +
+        'dedupe key, `lastStatusCode` and `lastError` describe the latest attempt only. When ' +
+        'nextCursor is non-null, call again with cursor set to it.',
+      inputSchema: {
+        workspace: workspaceInput,
+        webhookId: webhookIdInput,
+        status: webhookDeliveryStatusSchema
+          .optional()
+          .describe(
+            '`pending` (waiting for an attempt or a retry), `delivered`, `failed`, or `held` (out of ' +
+              'retries, kept for a redelivery).'
+          ),
+        limit: limitInput,
+        cursor: cursorInput
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace, webhookId, status, limit, cursor }) =>
+      run(webhooksScope, workspace, (c) =>
+        callApi(c, pageQuery(`${base}/${webhookId}/deliveries`, { cursor, limit }, { status }))
+      )
+  );
+
+  server.registerTool(
+    t('get_webhook_delivery'),
+    {
+      description:
+        `Read one delivery of a webhook, with the payload as sent and its latest attempt. ${WHO_MANAGES} ` +
+        `Returns the delivery as ${t('list_webhook_deliveries')} shows it.`,
+      inputSchema: { workspace: workspaceInput, webhookId: webhookIdInput, deliveryId: deliveryIdInput },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ workspace, webhookId, deliveryId }) =>
+      run(webhooksScope, workspace, (c) => callApi(c, `${base}/${webhookId}/deliveries/${deliveryId}`))
+  );
+
+  server.registerTool(
+    t('redeliver_webhook'),
+    {
+      description:
+        'Send one delivery’s event to its webhook again, as a new delivery — confirm with the user ' +
+        `first. ${WHO_MANAGES} The new delivery carries the same \`eventId\` (the receiver’s dedupe key) ` +
+        'and the same payload, and is queued: read its outcome later with ' +
+        `${t('get_webhook_delivery')}. Returns the new delivery.`,
+      inputSchema: { workspace: workspaceInput, webhookId: webhookIdInput, deliveryId: deliveryIdInput }
+    },
+    async ({ workspace, webhookId, deliveryId }) =>
+      run(webhooksScope, workspace, (c) =>
+        callApi(c, `${base}/${webhookId}/deliveries/${deliveryId}/redeliver`, send('POST'))
+      )
+  );
+}