@antasphere/chassis-server 1.1.0 → 1.2.0

package/src/api/webhooks.ts

@@ -0,0 +1,205 @@
+import type { OpenAPIHono } from '@hono/zod-openapi';
+import type { Principal } from '@antasphere/chassis-contract';
+import {
+  webhookCatalogRoute,
+  webhookCreateRoute,
+  webhookDeleteRoute,
+  webhookDeliveriesListRoute,
+  webhookDeliveryGetRoute,
+  webhookGetRoute,
+  webhookRedeliverRoute,
+  webhookRotateSecretRoute,
+  webhooksListRoute,
+  webhookTestRoute,
+  webhookUpdateRoute
+} from '@antasphere/chassis-contract/routes';
+import { requireAuth, requireNonGuest } from '../middleware/auth-context.js';
+import { catalogToWire, WebhookRefusedError, type WebhookService } from '../webhooks/index.js';
+
+/**
+ * The webhook routes (PRDCT-3482), the same on both editions and never
+ * hub-managed: a webhook is the tool's, on a self-hosted instance and on
+ * the cloud alike (Romain's rule of 27 September 2026).
+ *
+ * A webhook is a standing read of the workspace to a URL of the caller's
+ * choice, so the whole family, reads included, is an OWNER's or an ADMIN's
+ * act, checked inside each handler (never a path-pattern `requireRole`, the
+ * `/thing/:id` trap: the catalog lives under the same prefix and is every
+ * non-guest member's). A guest is refused flat; a session a demo link
+ * opened is refused every write (`DEMO_SESSION_REFUSED_API_ROUTES`); a
+ * machine principal needs the tool's dedicated scope (`middleware/scopes.ts`).
+ * An endpoint of another workspace reads as absent: 404, never 403.
+ *
+ * The secret is answered ONCE, at creation and at rotation, and never
+ * written to the audit row.
+ */
+export interface WebhookRouteDeps {
+  service: WebhookService;
+}
+
+const err = (code: string, message: string) => ({ error: { code, message } });
+const FORBIDDEN = err('forbidden', 'Only an owner or an admin manages webhooks');
+const NOT_FOUND = err('not_found', 'Webhook not found');
+const DELIVERY_NOT_FOUND = err('not_found', 'Delivery not found');
+
+const canManage = (principal: Principal) => principal.role === 'owner' || principal.role === 'admin';
+
+export function registerWebhookRoutes(api: OpenAPIHono, deps: WebhookRouteDeps): void {
+  const { service } = deps;
+
+  for (const path of ['/webhooks', '/webhooks/*']) {
+    api.use(path, requireAuth());
+    api.use(path, requireNonGuest());
+  }
+
+  // The catalog BEFORE the `{id}` routes: `events` is not an id. Every
+  // non-guest member reads it (an agent discovers the types with a read key).
+  api.openapi(webhookCatalogRoute, async (c) => c.json(catalogToWire(service.catalog), 200));
+
+  api.openapi(webhooksListRoute, async (c) => {
+    const principal = c.get('principal')!;
+    if (!canManage(principal)) return c.json(FORBIDDEN, 403);
+    const { cursor, limit } = c.req.valid('query');
+    return c.json(await service.list(principal.workspaceId, cursor, limit), 200);
+  });
+
+  api.openapi(webhookCreateRoute, async (c) => {
+    const principal = c.get('principal')!;
+    if (!canManage(principal)) return c.json(FORBIDDEN, 403);
+    const body = c.req.valid('json');
+    let created: Awaited<ReturnType<WebhookService['create']>>;
+    try {
+      created = await service.create(principal.workspaceId, principal.userId, body);
+    } catch (e) {
+      if (e instanceof WebhookRefusedError && e.code !== 'not_found')
+        return c.json(err(e.code, e.message), 400);
+      throw e;
+    }
+    c.set('audit', {
+      action: 'webhook.create',
+      resourceType: 'webhook',
+      resourceId: created.endpoint.id,
+      metadata: {
+        url: created.endpoint.url,
+        events: created.endpoint.events,
+        filters: created.endpoint.filters
+      }
+    });
+    return c.json({ ...created.endpoint, secret: created.secret }, 201);
+  });
+
+  api.openapi(webhookGetRoute, async (c) => {
+    const principal = c.get('principal')!;
+    if (!canManage(principal)) return c.json(FORBIDDEN, 403);
+    const { id } = c.req.valid('param');
+    const endpoint = await service.get(principal.workspaceId, id);
+    return endpoint ? c.json(endpoint, 200) : c.json(NOT_FOUND, 404);
+  });
+
+  api.openapi(webhookUpdateRoute, async (c) => {
+    const principal = c.get('principal')!;
+    if (!canManage(principal)) return c.json(FORBIDDEN, 403);
+    const { id } = c.req.valid('param');
+    const body = c.req.valid('json');
+    let updated: Awaited<ReturnType<WebhookService['update']>>;
+    try {
+      updated = await service.update(principal.workspaceId, id, body);
+    } catch (e) {
+      if (e instanceof WebhookRefusedError && e.code !== 'not_found')
+        return c.json(err(e.code, e.message), 400);
+      throw e;
+    }
+    if (!updated) return c.json(NOT_FOUND, 404);
+    c.set('audit', {
+      action: 'webhook.update',
+      resourceType: 'webhook',
+      resourceId: id,
+      metadata: { fields: Object.keys(body) }
+    });
+    return c.json(updated, 200);
+  });
+
+  api.openapi(webhookDeleteRoute, async (c) => {
+    const principal = c.get('principal')!;
+    if (!canManage(principal)) return c.json(FORBIDDEN, 403);
+    const { id } = c.req.valid('param');
+    const removed = await service.remove(principal.workspaceId, id);
+    if (!removed) return c.json(NOT_FOUND, 404);
+    c.set('audit', {
+      action: 'webhook.delete',
+      resourceType: 'webhook',
+      resourceId: id,
+      metadata: { url: removed.url }
+    });
+    return c.json(removed, 200);
+  });
+
+  api.openapi(webhookRotateSecretRoute, async (c) => {
+    const principal = c.get('principal')!;
+    if (!canManage(principal)) return c.json(FORBIDDEN, 403);
+    const { id } = c.req.valid('param');
+    const rotated = await service.rotateSecret(principal.workspaceId, id);
+    if (!rotated) return c.json(NOT_FOUND, 404);
+    c.set('audit', {
+      action: 'webhook.rotate_secret',
+      resourceType: 'webhook',
+      resourceId: id,
+      metadata: { previousSecretExpiresAt: rotated.previousSecretExpiresAt }
+    });
+    return c.json(
+      {
+        ...rotated.endpoint,
+        secret: rotated.secret,
+        previousSecretExpiresAt: rotated.previousSecretExpiresAt
+      },
+      200
+    );
+  });
+
+  api.openapi(webhookTestRoute, async (c) => {
+    const principal = c.get('principal')!;
+    if (!canManage(principal)) return c.json(FORBIDDEN, 403);
+    const { id } = c.req.valid('param');
+    const delivery = await service.test(principal.workspaceId, id, principal.userId);
+    if (!delivery) return c.json(NOT_FOUND, 404);
+    c.set('audit', {
+      action: 'webhook.test',
+      resourceType: 'webhook',
+      resourceId: id,
+      metadata: { deliveryId: delivery.id, status: delivery.status, lastStatusCode: delivery.lastStatusCode }
+    });
+    return c.json({ delivery }, 200);
+  });
+
+  api.openapi(webhookDeliveriesListRoute, async (c) => {
+    const principal = c.get('principal')!;
+    if (!canManage(principal)) return c.json(FORBIDDEN, 403);
+    const { id } = c.req.valid('param');
+    const { cursor, limit, status } = c.req.valid('query');
+    const page = await service.listDeliveries(principal.workspaceId, id, { cursor, limit, status });
+    return page ? c.json(page, 200) : c.json(NOT_FOUND, 404);
+  });
+
+  api.openapi(webhookDeliveryGetRoute, async (c) => {
+    const principal = c.get('principal')!;
+    if (!canManage(principal)) return c.json(FORBIDDEN, 403);
+    const { id, deliveryId } = c.req.valid('param');
+    const delivery = await service.getDelivery(principal.workspaceId, id, deliveryId);
+    return delivery ? c.json(delivery, 200) : c.json(DELIVERY_NOT_FOUND, 404);
+  });
+
+  api.openapi(webhookRedeliverRoute, async (c) => {
+    const principal = c.get('principal')!;
+    if (!canManage(principal)) return c.json(FORBIDDEN, 403);
+    const { id, deliveryId } = c.req.valid('param');
+    const delivery = await service.redeliver(principal.workspaceId, id, deliveryId);
+    if (!delivery) return c.json(DELIVERY_NOT_FOUND, 404);
+    c.set('audit', {
+      action: 'webhook.redeliver',
+      resourceType: 'webhook',
+      resourceId: id,
+      metadata: { deliveryId: delivery.id, eventId: delivery.eventId, eventType: delivery.eventType }
+    });
+    return c.json(delivery, 201);
+  });
+}

package/src/boot.ts

@@ -52,6 +52,8 @@ import { createOtel } from './observability/index.js';
 import { bindEditionSeams } from './platform/index.js';
 import { AllowAllEntitlements } from './platform/index.js';
 import { EventBus } from './platform/index.js';
+import { buildWebhookCatalog, WebhookService, webhookJobs } from './webhooks/index.js';
+import { bindMembershipRemoval } from './members/removal.js';
 import { LocalIdentityProvider } from './platform/index.js';
 import { createRegistry } from './platform/index.js';
 import { NoopUsageSink } from './platform/index.js';
@@ -540,6 +542,26 @@ export async function bootPlatform<
     }
   }
 
+  // Outbound webhooks (PRDCT-3482): the catalog checked, the service built
+  // BEFORE the job runtime (its four queues are declared to it like a tool's
+  // own) and attached to it right after; a tool's `services` slot receives
+  // the emitter, the API app the service, the bus the chassis's own events.
+  const webhookCatalog = buildWebhookCatalog(tool.webhooks);
+  const webhooks = new WebhookService({
+    db: db.db,
+    logger,
+    authSecret,
+    identity: tool.identity,
+    version: tool.runtime.version,
+    policy: { allowPrivateNetworks: env.WEBHOOKS_ALLOW_PRIVATE_NETWORKS, httpsOnly: env.EDITION === 'cloud' },
+    email,
+    brand: { name: tool.identity.displayName, tagline: tool.copy.mail.tagline },
+    publicBaseUrl: env.PUBLIC_BASE_URL,
+    catalog: webhookCatalog,
+    dials: overrides.webhookDials,
+    fetchOptions: overrides.webhookFetch
+  });
+
   // The live user-scoped federation stack (cloud only, internal/federation.md):
   // each user's OWN hub grant (offline_access refresh token on the account
   // row) → as-the-user `GET /orgs` reads → the org reconciler that the
@@ -611,7 +633,7 @@ export async function bootPlatform<
           audit,
           logger,
           dials: hubDials,
-          onMembershipRemoval: tool.membershipRemoval,
+          onMembershipRemoval: bindMembershipRemoval(tool.membershipRemoval, { webhooks }),
           ...(overrides.hubNow ? { now: overrides.hubNow } : {})
         })
       : undefined;
@@ -662,9 +684,14 @@ export async function bootPlatform<
     overrides.usageDownstream ?? hubUsagePoster ?? new NoopUsageSink(),
     auth,
     audit,
-    tool.jobs?.({ env, db: db.db, logger, getTool: () => domainRef.current }) ?? [],
+    [
+      ...webhookJobs(webhooks, logger, env.WEBHOOK_DELIVERY_RETENTION_DAYS),
+      ...(tool.jobs?.({ env, db: db.db, logger, getTool: () => domainRef.current }) ?? [])
+    ],
     usageRetry
   );
+  webhooks.attach(jobs.boss);
+  webhooks.bindBus(events.chassisView());
   // The tool's billing-rail declarations (slot 22), asserted once here: a
   // route that meters an action the price book does not know, or a limit no
   // tier values, stops the boot naming the route.
@@ -806,6 +833,7 @@ export async function bootPlatform<
     events,
     authSecret,
     timers: jobs.timers,
+    webhooks,
     overrides: overrides.tool
   };
   const domain = tool.services(serviceCore);
@@ -849,6 +877,7 @@ export async function bootPlatform<
     principalGate: seams.principalGate,
     entitlements,
     entitlementCloud,
+    webhooks,
     // Cloud only (PRDCT-2443): POST /workspaces creates the organization at
     // the hub AS THE CALLER, then forces their reconcile. undefined on oss —
     // the route creates locally there.
@@ -885,7 +914,8 @@ export async function bootPlatform<
     ...(hubGrant?.promMetrics ?? []),
     ...(hubUsagePoster?.promMetrics ?? []),
     ...(hubCreditCheck?.promMetrics ?? []),
-    ...jobs.promMetrics
+    ...jobs.promMetrics,
+    ...webhooks.promMetrics
   ]) {
     metrics.registry.registerMetric(metric);
   }
@@ -952,5 +982,19 @@ export async function bootPlatform<
     state.reason = readinessRefusal;
   }
 
-  return { app, env, logger, state, db, auth, registry, jobs, email, otel, authSecret, tool: domain };
+  return {
+    app,
+    env,
+    logger,
+    state,
+    db,
+    auth,
+    registry,
+    jobs,
+    email,
+    otel,
+    authSecret,
+    webhooks,
+    tool: domain
+  };
 }

package/src/email/index.ts

@@ -24,3 +24,4 @@ export {
   buildPasswordResetEmail,
   buildVerifyEmailEmail
 } from './templates.js';
+export { buildWebhookDisabledEmail, type WebhookDisabledEmailParams } from '../webhooks/mail.js';

package/src/env.ts

@@ -266,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. */
@@ -372,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.'
       );
     }