@vellumai/assistant 0.11.9-dev.202609080319.eb4f1b0 → 0.11.9-dev.202609080628.cb7bdcf

package/node_modules/@vellumai/gateway-client/src/gateway-ipc-contracts.ts

@@ -401,6 +401,78 @@ export type ContactsIdentitySnapshotIpcResponse = z.infer<
   typeof ContactsIdentitySnapshotIpcResponseSchema
 >;
 
+// ── webhook ingress routes ───────────────────────────────────────────────────
+// The gateway owns the registry of subpaths this assistant answers from
+// outside; the daemon claims, drops, and inspects them over IPC. Both sides
+// read these schemas so a change to the stored row has to travel through the
+// contract.
+
+/**
+ * Feature flag gating the whole webhook ingress registry. The gateway reads it
+ * to decide whether to accept a claim and how to advertise its allowed paths,
+ * and the daemon reads it to decide whether to claim at all, so both sides have
+ * to name the same key.
+ */
+export const WebhookIngressRouteSchema = z.object({
+  path: z.string(),
+  type: z.string(),
+  source: z.string().nullable(),
+  match: z.literal("exact"),
+  createdAt: z.number(),
+  lastRegisteredAt: z.number(),
+});
+
+export type WebhookIngressRoute = z.infer<typeof WebhookIngressRouteSchema>;
+
+export const RegisterWebhookRouteIpcParamsSchema = z.object({
+  /** Exact subpath, leading slash included, under `/webhooks/`. */
+  path: z.string().min(1),
+  type: z.string().min(1),
+  source: z.string().nullish(),
+});
+
+export type RegisterWebhookRouteIpcParams = z.infer<
+  typeof RegisterWebhookRouteIpcParamsSchema
+>;
+
+/**
+ * A refusal is a normal result rather than an error: the daemon reads
+ * `disabled` as "this assistant is not serving its own webhooks" and falls
+ * back to the platform's callback routes.
+ */
+export const RegisterWebhookRouteIpcResponseSchema = z.union([
+  z.object({ disabled: z.literal(true) }),
+  z.object({ disabled: z.literal(false), route: WebhookIngressRouteSchema }),
+]);
+
+export type RegisterWebhookRouteIpcResponse = z.infer<
+  typeof RegisterWebhookRouteIpcResponseSchema
+>;
+
+export const UnregisterWebhookRouteIpcParamsSchema = z.object({
+  path: z.string().min(1),
+});
+
+export type UnregisterWebhookRouteIpcParams = z.infer<
+  typeof UnregisterWebhookRouteIpcParamsSchema
+>;
+
+export const UnregisterWebhookRouteIpcResponseSchema = z.object({
+  removed: z.boolean(),
+});
+
+export type UnregisterWebhookRouteIpcResponse = z.infer<
+  typeof UnregisterWebhookRouteIpcResponseSchema
+>;
+
+export const ListWebhookRoutesIpcResponseSchema = z.object({
+  routes: z.array(WebhookIngressRouteSchema),
+});
+
+export type ListWebhookRoutesIpcResponse = z.infer<
+  typeof ListWebhookRoutesIpcResponseSchema
+>;
+
 // ── classify_risk ────────────────────────────────────────────────────────────
 // Risk classification is gateway-owned; the assistant sends one request per
 // tool invocation and reads the whole answer back. The gateway validates the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.9-dev.202609080319.eb4f1b0",
+  "version": "0.11.9-dev.202609080628.cb7bdcf",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/platform-callback-registration.test.ts

@@ -1,15 +1,35 @@
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
+import type { RegisterWebhookRouteIpcParams } from "@vellumai/gateway-client";
+
 import { setIngressPublicBaseUrl } from "../config/env.js";
+import type { IpcRegisterWebhookRouteResult } from "../ipc/gateway-client.js";
 import { credentialKey } from "../security/credential-key.js";
 
 let mockIsPlatform = true;
+let mockVelayWebhooksEnabled = false;
 let mockPlatformBaseUrl = "";
 let mockPlatformAssistantId = "";
 let mockSecureKeys: Record<string, string> = {};
 let mockConfig: { ingress?: { publicBaseUrl?: string; enabled?: boolean } } =
   {};
 
+const REGISTERED_ROUTE = {
+  path: "/webhooks/twilio/voice",
+  type: "twilio_voice",
+  source: null,
+  match: "exact" as const,
+  createdAt: 1,
+  lastRegisteredAt: 1,
+};
+
+let mockRegisterWebhookRouteResult: IpcRegisterWebhookRouteResult = {
+  ok: true,
+  disabled: false,
+  route: REGISTERED_ROUTE,
+};
+let ipcRegisterCalls: RegisterWebhookRouteIpcParams[] = [];
+
 // Bun shares mocked modules across test files in a combined run, so each mock
 // spreads the real module and overrides only what this file drives. Replacing
 // a module wholesale drops the exports peer tests import from it and breaks
@@ -20,6 +40,12 @@ mock.module("../config/env-registry.js", () => ({
   getIsPlatform: () => mockIsPlatform,
 }));
 
+const actualVelayGate = await import("../inbound/velay-webhooks-gate.js");
+mock.module("../inbound/velay-webhooks-gate.js", () => ({
+  ...actualVelayGate,
+  isVelayWebhooksEnabled: () => mockVelayWebhooksEnabled,
+}));
+
 const actualEnv = await import("../config/env.js");
 mock.module("../config/env.js", () => ({
   ...actualEnv,
@@ -27,6 +53,15 @@ mock.module("../config/env.js", () => ({
   getPlatformAssistantId: () => mockPlatformAssistantId,
 }));
 
+const actualGatewayClient = await import("../ipc/gateway-client.js");
+mock.module("../ipc/gateway-client.js", () => ({
+  ...actualGatewayClient,
+  ipcRegisterWebhookRoute: async (input: RegisterWebhookRouteIpcParams) => {
+    ipcRegisterCalls.push(input);
+    return mockRegisterWebhookRouteResult;
+  },
+}));
+
 const actualSecureKeys = await import("../security/secure-keys.js");
 mock.module("../security/secure-keys.js", () => ({
   ...actualSecureKeys,
@@ -207,9 +242,7 @@ describe("platform callback registration", () => {
 
     await expect(
       registerCallbackRoute("webhooks/telegram", "telegram"),
-    ).resolves.toBe(
-      "https://my-assistant.example.com/v1/gateway/callbacks/x/",
-    );
+    ).resolves.toBe("https://my-assistant.example.com/v1/gateway/callbacks/x/");
   });
 
   test("self-hosted registerCallbackRoute sends detected module-level callback_base_url", async () => {
@@ -373,6 +406,7 @@ describe("resolveCallbackUrl resolution order", () => {
 
   beforeEach(() => {
     mockIsPlatform = false;
+    mockVelayWebhooksEnabled = false;
     mockPlatformBaseUrl = "";
     mockPlatformAssistantId = "";
     mockSecureKeys = {};
@@ -380,6 +414,12 @@ describe("resolveCallbackUrl resolution order", () => {
     setIngressPublicBaseUrl(undefined);
     delete process.env.ASSISTANT_API_KEY;
     registerCalls = 0;
+    ipcRegisterCalls = [];
+    mockRegisterWebhookRouteResult = {
+      ok: true,
+      disabled: false,
+      route: REGISTERED_ROUTE,
+    };
     globalThis.fetch = mock(async () => {
       registerCalls++;
       return new Response(
@@ -408,6 +448,124 @@ describe("resolveCallbackUrl resolution order", () => {
       resolveCallbackUrl(noIngress, "webhooks/twilio/voice", "twilio_voice"),
     ).resolves.toBe(PLATFORM_URL);
     expect(registerCalls).toBe(1);
+    expect(ipcRegisterCalls).toEqual([]);
+  });
+
+  test("velay-webhooks on: a pod claims the subpath and uses the published URL", async () => {
+    mockIsPlatform = true;
+    mockVelayWebhooksEnabled = true;
+    seedPlatformCredentials();
+
+    await expect(
+      resolveCallbackUrl(
+        () => "https://velay.example.com/assistant-1/webhooks/twilio/voice",
+        "webhooks/twilio/voice",
+        "twilio_voice",
+        { callSessionId: "conv-xyz" },
+        "+15555550142",
+      ),
+    ).resolves.toBe(
+      "https://velay.example.com/assistant-1/webhooks/twilio/voice",
+    );
+    expect(registerCalls).toBe(0);
+    expect(ipcRegisterCalls).toEqual([
+      {
+        path: "/webhooks/twilio/voice",
+        type: "twilio_voice",
+        source: "+15555550142",
+      },
+    ]);
+  });
+
+  test("velay-webhooks on: a refused claim falls back to the platform", async () => {
+    mockIsPlatform = true;
+    mockVelayWebhooksEnabled = true;
+    mockRegisterWebhookRouteResult = { ok: true, disabled: true };
+    seedPlatformCredentials();
+
+    await expect(
+      resolveCallbackUrl(
+        () => "https://velay.example.com/assistant-1/webhooks/twilio/voice",
+        "webhooks/twilio/voice",
+        "twilio_voice",
+      ),
+    ).resolves.toBe(PLATFORM_URL);
+    expect(registerCalls).toBe(1);
+    expect(ipcRegisterCalls).toHaveLength(1);
+  });
+
+  test("velay-webhooks on: an unreachable gateway falls back to the platform", async () => {
+    mockIsPlatform = true;
+    mockVelayWebhooksEnabled = true;
+    mockRegisterWebhookRouteResult = { ok: false, reason: "no_response" };
+    seedPlatformCredentials();
+
+    await expect(
+      resolveCallbackUrl(
+        () => "https://velay.example.com/assistant-1/webhooks/twilio/voice",
+        "webhooks/twilio/voice",
+        "twilio_voice",
+      ),
+    ).resolves.toBe(PLATFORM_URL);
+    expect(registerCalls).toBe(1);
+    expect(ipcRegisterCalls).toHaveLength(1);
+  });
+
+  test("velay-webhooks on: a pod with no published URL still registers with the platform", async () => {
+    mockIsPlatform = true;
+    mockVelayWebhooksEnabled = true;
+    seedPlatformCredentials();
+
+    await expect(
+      resolveCallbackUrl(noIngress, "webhooks/twilio/voice", "twilio_voice"),
+    ).resolves.toBe(PLATFORM_URL);
+    expect(registerCalls).toBe(1);
+    expect(ipcRegisterCalls).toEqual([]);
+  });
+
+  test("velay-webhooks on: a pod with ingress disabled falls back instead of throwing", async () => {
+    mockIsPlatform = true;
+    mockVelayWebhooksEnabled = true;
+    seedPlatformCredentials();
+
+    await expect(
+      resolveCallbackUrl(
+        ingressDisabled,
+        "webhooks/twilio/voice",
+        "twilio_voice",
+      ),
+    ).resolves.toBe(PLATFORM_URL);
+    expect(registerCalls).toBe(1);
+    expect(ipcRegisterCalls).toEqual([]);
+  });
+
+  test("velay-webhooks on: self-hosted opt-out still surfaces", async () => {
+    mockVelayWebhooksEnabled = true;
+    seedPlatformCredentials();
+
+    await expect(
+      resolveCallbackUrl(
+        ingressDisabled,
+        "webhooks/twilio/voice",
+        "twilio_voice",
+      ),
+    ).rejects.toThrow("Public ingress is disabled");
+    expect(registerCalls).toBe(0);
+    expect(ipcRegisterCalls).toEqual([]);
+  });
+
+  test("velay-webhooks on: a self-hosted ingress URL is not claimed on the gateway", async () => {
+    mockVelayWebhooksEnabled = true;
+    seedPlatformCredentials();
+
+    await expect(
+      resolveCallbackUrl(
+        () => "https://tunnel.example.com/webhooks/twilio/voice",
+        "webhooks/twilio/voice",
+        "twilio_voice",
+      ),
+    ).resolves.toBe("https://tunnel.example.com/webhooks/twilio/voice");
+    expect(ipcRegisterCalls).toEqual([]);
   });
 
   test("a configured ingress wins over platform connectivity", async () => {
@@ -421,6 +579,7 @@ describe("resolveCallbackUrl resolution order", () => {
       ),
     ).resolves.toBe("https://tunnel.example.com/webhooks/twilio/voice");
     expect(registerCalls).toBe(0);
+    expect(ipcRegisterCalls).toEqual([]);
   });
 
   test("a platform-connected assistant with no ingress registers with the platform", async () => {

package/src/__tests__/plugin-api-webhook-url.test.ts

@@ -8,13 +8,29 @@
  * registration type it derives, and what it refuses.
  */
 
-import { describe, expect, spyOn, test } from "bun:test";
+import { afterEach, describe, expect, mock, spyOn, test } from "bun:test";
 
-import * as registration from "../inbound/platform-callback-registration.js";
-import { resolveWebhookUrl } from "../plugin-api/webhook-url.js";
-import { runInPluginContext } from "../plugins/plugin-execution-context.js";
+let mockIsPlatform = false;
+
+// Bun shares mocked modules across test files in a combined run, so the mock
+// spreads the real module and overrides only what this file drives.
+const actualEnvRegistry = await import("../config/env-registry.js");
+mock.module("../config/env-registry.js", () => ({
+  ...actualEnvRegistry,
+  getIsPlatform: () => mockIsPlatform,
+}));
+
+const loader = await import("../config/loader.js");
+const registration =
+  await import("../inbound/platform-callback-registration.js");
+const { resolveWebhookUrl } = await import("../plugin-api/webhook-url.js");
+const { runInPluginContext } =
+  await import("../plugins/plugin-execution-context.js");
 
 describe("resolveWebhookUrl", () => {
+  afterEach(() => {
+    mockIsPlatform = false;
+  });
   test("composes the plugin's namespaced path and delegates the tier choice", async () => {
     const spy = spyOn(registration, "resolveCallbackUrl").mockResolvedValue(
       "https://callbacks.vellum.ai/abc/webhooks/plugins/imessage/events-photon",
@@ -143,6 +159,52 @@ describe("resolveWebhookUrl", () => {
     spy.mockRestore();
   });
 
+  test("hands out an ingress URL under exactly the path it claimed", async () => {
+    // The Velay tunnel forwards the request path verbatim and the gateway
+    // admits it only when it matches a claimed path byte for byte. A trailing
+    // slash on this URL would be rejected before the gateway ever saw it.
+    mockIsPlatform = true;
+    const configSpy = spyOn(loader, "getConfig").mockReturnValue({
+      ingress: { publicBaseUrl: "https://velay.vellum.ai/assistant-abc" },
+    } as ReturnType<typeof loader.getConfig>);
+    const spy = spyOn(registration, "resolveCallbackUrl").mockImplementation(
+      async (directUrl) => directUrl(),
+    );
+
+    const url = await resolveWebhookUrl({
+      plugin: "imessage",
+      path: "events-photon",
+    });
+
+    const claimedPath = `/${spy.mock.calls[0]![1]}`;
+    expect(claimedPath).toBe("/webhooks/plugins/imessage/events-photon");
+    expect(new URL(url).pathname).toBe(`/assistant-abc${claimedPath}`);
+    spy.mockRestore();
+    configSpy.mockRestore();
+  });
+
+  test("keeps the trailing slash on a self-hosted ingress URL", async () => {
+    // Off a pod the direct URL never rides the tunnel, so the spelling stays
+    // what it always was.
+    const configSpy = spyOn(loader, "getConfig").mockReturnValue({
+      ingress: { publicBaseUrl: "https://assistant.example.test" },
+    } as ReturnType<typeof loader.getConfig>);
+    const spy = spyOn(registration, "resolveCallbackUrl").mockImplementation(
+      async (directUrl) => directUrl(),
+    );
+
+    const url = await resolveWebhookUrl({
+      plugin: "imessage",
+      path: "events-photon",
+    });
+
+    expect(url).toBe(
+      "https://assistant.example.test/webhooks/plugins/imessage/events-photon/",
+    );
+    spy.mockRestore();
+    configSpy.mockRestore();
+  });
+
   test("leaves a URL carrying a query string alone", async () => {
     // Appending there would cut into the query rather than the path.
     const spy = spyOn(registration, "resolveCallbackUrl").mockResolvedValue(

package/src/cli/commands/__tests__/conversations-slack.test.ts

@@ -95,6 +95,18 @@ mock.module("../../../ipc/gateway-client.js", () => ({
   ipcGetFeatureFlags: async () => ({}),
   ipcGetVelayStatus: async () => null,
   ipcClassifyRisk: async () => ({ risk: "low" }),
+  ipcRegisterWebhookRoute: async () => ({
+    ok: false as const,
+    reason: "no_response" as const,
+  }),
+  ipcUnregisterWebhookRoute: async () => ({
+    ok: false as const,
+    reason: "no_response" as const,
+  }),
+  ipcListWebhookRoutes: async () => ({
+    ok: false as const,
+    reason: "no_response" as const,
+  }),
 }));
 
 mock.module("../../../messaging/providers/slack/send.js", () => ({

package/src/config/__tests__/webhook-routing.test.ts

@@ -12,6 +12,7 @@
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
 let isPlatform = false;
+let velayWebhooksEnabled = false;
 let rawConfig: Record<string, unknown> = {};
 let platformContextEnabled = false;
 
@@ -30,6 +31,12 @@ mock.module("../loader.js", () => ({
   getConfig: () => rawConfig,
 }));
 
+const actualVelayGate = await import("../../inbound/velay-webhooks-gate.js");
+mock.module("../../inbound/velay-webhooks-gate.js", () => ({
+  ...actualVelayGate,
+  isVelayWebhooksEnabled: () => velayWebhooksEnabled,
+}));
+
 const actualRegistration =
   await import("../../inbound/platform-callback-registration.js");
 mock.module("../../inbound/platform-callback-registration.js", () => ({
@@ -50,6 +57,7 @@ const { hasIngressConfigured, hasWebhookRoutingConfigured } =
 describe("hasWebhookRoutingConfigured resolution order", () => {
   beforeEach(() => {
     isPlatform = false;
+    velayWebhooksEnabled = false;
     rawConfig = {};
     platformContextEnabled = false;
   });
@@ -78,6 +86,40 @@ describe("hasWebhookRoutingConfigured resolution order", () => {
     });
   });
 
+  test("velay-webhooks on: a pod with a published ingress URL reports it", async () => {
+    isPlatform = true;
+    velayWebhooksEnabled = true;
+    rawConfig = { ingress: { publicBaseUrl: "https://tunnel.example.com" } };
+
+    expect(await hasWebhookRoutingConfigured(true)).toEqual({
+      configured: true,
+      usesManagedCallbacks: false,
+    });
+  });
+
+  test("velay-webhooks on: a pod with no published URL still reports managed", async () => {
+    isPlatform = true;
+    velayWebhooksEnabled = true;
+
+    expect(await hasWebhookRoutingConfigured(true)).toEqual({
+      configured: true,
+      usesManagedCallbacks: true,
+    });
+  });
+
+  test("velay-webhooks on: a pod with ingress disabled falls back to managed", async () => {
+    isPlatform = true;
+    velayWebhooksEnabled = true;
+    rawConfig = { ingress: { enabled: false } };
+
+    // Matches `resolveCallbackUrl` on pods: an owner toggling ingress off
+    // must not lose webhooks entirely.
+    expect(await hasWebhookRoutingConfigured(true)).toEqual({
+      configured: true,
+      usesManagedCallbacks: true,
+    });
+  });
+
   // ── Tier 2: a configured ingress wins ────────────────────────────────────
 
   test("ingress beats the platform-connected fallback", async () => {

package/src/config/feature-flag-registry.json

@@ -446,6 +446,14 @@
       "label": "Model-First Profile Create",
       "description": "Reverses the two questions the web client's New Model modal asks when creating an inference profile. Off: the modal asks for a provider first and then offers that provider's models. On: it opens on one searchable list of every catalog model the assistant can reach, deduplicated across providers, and only then asks which provider serves the chosen model. That second question is skipped when a single provider serves it, answered with radio cards when several do, and turned into an inline connect form (API key, setup, or ChatGPT sign-in) when the chosen route has no connection yet. Editing an existing profile is unchanged either way, and both flows persist the same profile shape.",
       "defaultEnabled": false
+    },
+    {
+      "id": "velay-webhooks",
+      "scope": "assistant",
+      "key": "velay-webhooks",
+      "label": "Velay Webhooks",
+      "description": "Platform pods resolve webhook callback URLs from the Velay-published ingress URL instead of registering platform callback routes. Falls back to platform callback registration while no tunnel URL is published.",
+      "defaultEnabled": false
     }
   ]
 }

package/src/config/webhook-routing.ts

@@ -16,6 +16,7 @@ import {
 
 import { resolvePlatformCallbackRegistrationContext } from "../inbound/platform-callback-registration.js";
 import { isPublicIngressDisabled } from "../inbound/public-ingress-urls.js";
+import { isVelayWebhooksEnabled } from "../inbound/velay-webhooks-gate.js";
 import { getIsPlatform } from "./env-registry.js";
 import { getConfig, loadRawConfig } from "./loader.js";
 
@@ -67,7 +68,11 @@ function isIngressExplicitlyDisabled(): boolean {
  * reports "no ingress" while `webhooks register` hands back a working callback
  * URL hides a broken registration instead of surfacing it.
  *
- *   1. **Platform pods** (`IS_PLATFORM`) always use managed callbacks.
+ *   1. **Platform pods** (`IS_PLATFORM`) with the `velay-webhooks` flag off
+ *      always use managed callbacks. With the flag on, a configured ingress
+ *      (the Velay-published URL) wins, and managed callbacks remain the
+ *      fallback — including when ingress is explicitly disabled, matching
+ *      `resolveCallbackUrl`'s pod behavior.
  *   2. **A configured public ingress wins** for everyone else.
  *   3. **Platform-connected assistants with no ingress** fall back to managed
  *      callbacks. Connectivity is decided by credentials (platform base URL +
@@ -99,7 +104,8 @@ export async function hasWebhookRoutingConfigured(
   configured: boolean;
   usesManagedCallbacks: boolean;
 }> {
-  if (allowManagedCallbacks && getIsPlatform()) {
+  const platformManaged = allowManagedCallbacks && getIsPlatform();
+  if (platformManaged && !isVelayWebhooksEnabled()) {
     return { configured: true, usesManagedCallbacks: true };
   }
 
@@ -107,6 +113,10 @@ export async function hasWebhookRoutingConfigured(
     return { configured: true, usesManagedCallbacks: false };
   }
 
+  if (platformManaged) {
+    return { configured: true, usesManagedCallbacks: true };
+  }
+
   if (!allowManagedCallbacks || isIngressExplicitlyDisabled()) {
     return { configured: false, usesManagedCallbacks: false };
   }

package/src/inbound/platform-callback-registration.ts

@@ -21,13 +21,16 @@
 import { getPlatformAssistantId, getPlatformBaseUrl } from "../config/env.js";
 import { getIsPlatform } from "../config/env-registry.js";
 import { getConfig } from "../config/loader.js";
+import { ipcRegisterWebhookRoute } from "../ipc/gateway-client.js";
 import { credentialKey } from "../security/credential-key.js";
 import { getSecureKeyAsync } from "../security/secure-keys.js";
 import { getLogger } from "../util/logger.js";
+import { resolveClaimedPodWebhookUrl } from "./pod-webhook-claim.js";
 import {
   PublicIngressDisabledError,
   tryGetPublicBaseUrl,
 } from "./public-ingress-urls.js";
+import { isVelayWebhooksEnabled } from "./velay-webhooks-gate.js";
 
 const log = getLogger("platform-callback-registration");
 
@@ -177,6 +180,47 @@ function resolveSelfHostedCallbackBaseUrl(): string | undefined {
   }
 }
 
+/**
+ * Claim a webhook subpath on the gateway so the Velay tunnel forwards it.
+ *
+ * The registry matches paths exactly, so query parameters a caller appends to
+ * the resolved URL play no part. Returns false when the gateway declines the
+ * claim or cannot be reached, leaving platform callback registration as the
+ * way to keep the webhook reachable.
+ *
+ * @param callbackPath - The path to claim, e.g. "webhooks/twilio/voice".
+ */
+export async function registerLocalWebhookRoute(
+  callbackPath: string,
+  type: string,
+  sourceIdentifier?: string,
+): Promise<boolean> {
+  const path = callbackPath.startsWith("/") ? callbackPath : `/${callbackPath}`;
+  const result = await ipcRegisterWebhookRoute({
+    path,
+    type,
+    source: sourceIdentifier,
+  });
+
+  if (!result.ok) {
+    log.warn(
+      { path, type, reason: result.reason },
+      "Gateway webhook route registration failed, falling back to the platform",
+    );
+    return false;
+  }
+  if (result.disabled) {
+    log.info(
+      { path, type },
+      "Gateway is not serving its own webhooks, falling back to the platform",
+    );
+    return false;
+  }
+
+  log.debug({ path, type }, "Gateway webhook route registered");
+  return true;
+}
+
 /**
  * Resolve a callback URL, registering with the platform when appropriate.
  *
@@ -184,8 +228,15 @@ function resolveSelfHostedCallbackBaseUrl(): string | undefined {
  * `runtime/routes/webhook-routes.ts` and `hasWebhookRoutingConfigured` in
  * `config/webhook-routing.ts`:
  *
- *   1. **Platform pods** (`IS_PLATFORM`) always register with the platform
- *      gateway: they have no ingress of their own to advertise.
+ *   1. **Platform pods** (`IS_PLATFORM`) with the `velay-webhooks` flag off
+ *      always register with the platform gateway. With the flag on, they try
+ *      the direct supplier first — the gateway's Velay client publishes the
+ *      tunnel URL into `ingress.publicBaseUrl` — and fall back to platform
+ *      registration on any failure, including an explicit
+ *      `ingress.enabled: false`: a pod owner toggling that flag must not
+ *      lose webhooks entirely. The subpath is claimed on the gateway before
+ *      the tunnel URL is handed out, and a refused claim falls back the same
+ *      way.
  *   2. **A configured public ingress wins** for everyone else, so the direct
  *      supplier is tried first and its value returned when it resolves.
  *   3. **Platform-connected assistants with no ingress** register with the
@@ -194,12 +245,12 @@ function resolveSelfHostedCallbackBaseUrl(): string | undefined {
  *      ID + assistant API key), not by `IS_PLATFORM`, which is only ever true
  *      on a platform pod.
  *
- * An explicit `ingress.enabled: false` is a decision not to accept inbound
- * webhooks at all, so `PublicIngressDisabledError` propagates instead of being
- * routed around. Ingress precedes the platform fallback because any logged-in
- * local assistant holds platform credentials for the LLM proxy: treating
- * credential presence as "managed" would silently reroute an explicitly
- * configured self-hosted callback through the platform.
+ * Off a pod, an explicit `ingress.enabled: false` is a decision not to accept
+ * inbound webhooks at all, so `PublicIngressDisabledError` propagates instead
+ * of being routed around. Ingress precedes the platform fallback because any
+ * logged-in local assistant holds platform credentials for the LLM proxy:
+ * treating credential presence as "managed" would silently reroute an
+ * explicitly configured self-hosted callback through the platform.
  *
  * The `directUrl` parameter is a **lazy supplier** (a function returning a
  * string) rather than an eagerly-evaluated string. This is critical because
@@ -222,10 +273,20 @@ export async function resolveCallbackUrl(
   queryParams?: Record<string, string>,
   sourceIdentifier?: string,
 ): Promise<string> {
-  if (!getIsPlatform()) {
+  if (getIsPlatform()) {
+    if (isVelayWebhooksEnabled()) {
+      const claimed = await resolveClaimedPodWebhookUrl(directUrl, () =>
+        registerLocalWebhookRoute(callbackPath, type, sourceIdentifier),
+      );
+      if (claimed !== undefined) {
+        return claimed;
+      }
+    }
+  } else {
+    let ingressUrl: string | undefined;
     let ingressError: unknown;
     try {
-      return directUrl();
+      ingressUrl = directUrl();
     } catch (err) {
       if (err instanceof PublicIngressDisabledError) {
         throw err;
@@ -233,8 +294,13 @@ export async function resolveCallbackUrl(
       ingressError = err;
     }
 
+    if (ingressUrl !== undefined) {
+      return ingressUrl;
+    }
+
     // No ingress configured. Fall back to the platform gateway when this
-    // assistant is connected to the platform.
+    // assistant is connected to the platform. Platform pods always are, so
+    // they skip the context probe and register directly.
     const context = await resolvePlatformCallbackRegistrationContext();
     if (!context.enabled) {
       throw ingressError;

package/src/inbound/pod-webhook-claim.ts

@@ -0,0 +1,35 @@
+/**
+ * The platform-pod tier of webhook URL resolution, shared by the two seams that
+ * resolve callback URLs: `resolveCallbackUrl` and the `webhooks_register` route
+ * handler.
+ *
+ * A pod's Velay tunnel only forwards subpaths the gateway has claimed, so the
+ * published ingress URL is handed out only once the claim succeeds. Anything
+ * else leaves the caller to register with the platform instead.
+ */
+
+/**
+ * The published ingress URL for a webhook, or undefined when the pod should
+ * fall back to platform registration.
+ *
+ * `ingressUrl` is a lazy supplier because the builders behind it throw when no
+ * public base URL has been published yet, and on a pod that throw is not fatal:
+ * a pod owner with no tunnel yet, or one who turned ingress off, must not lose
+ * webhooks entirely.
+ *
+ * @param ingressUrl - Lazy supplier for the published ingress callback URL.
+ * @param claimRoute - Claims the subpath on the gateway; false when the gateway
+ *   refuses the claim or cannot be reached.
+ */
+export async function resolveClaimedPodWebhookUrl(
+  ingressUrl: () => string,
+  claimRoute: () => Promise<boolean>,
+): Promise<string | undefined> {
+  let url: string;
+  try {
+    url = ingressUrl();
+  } catch {
+    return undefined;
+  }
+  return (await claimRoute()) ? url : undefined;
+}

package/src/inbound/velay-webhooks-gate.ts

@@ -0,0 +1,20 @@
+import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
+
+const VELAY_WEBHOOKS_FLAG_KEY = "velay-webhooks" as const;
+
+/**
+ * Whether platform pods resolve webhook callback URLs from the
+ * Velay-published ingress URL instead of registering platform callback
+ * routes.
+ *
+ * Gates the platform-pod tier in all three webhook resolution sites
+ * (`resolveCallbackUrl`, `hasWebhookRoutingConfigured`,
+ * `handleWebhooksRegister`), which must agree tier for tier. Off means the
+ * pre-Velay behavior: platform pods always register with the platform
+ * gateway. On means ingress-first with platform registration as the
+ * fallback, so a pod whose tunnel has not published a URL yet keeps
+ * working either way.
+ */
+export function isVelayWebhooksEnabled(): boolean {
+  return isAssistantFeatureFlagEnabled(VELAY_WEBHOOKS_FLAG_KEY);
+}

package/src/ipc/gateway-client.ts

@@ -14,6 +14,11 @@ import {
   type ClassifyRiskIpcParams,
   type ClassifyRiskIpcResponse,
   ClassifyRiskIpcResponseSchema,
+  ListWebhookRoutesIpcResponseSchema,
+  type RegisterWebhookRouteIpcParams,
+  RegisterWebhookRouteIpcResponseSchema,
+  UnregisterWebhookRouteIpcResponseSchema,
+  type WebhookIngressRoute,
 } from "@vellumai/gateway-client";
 import {
   ipcCall as packageIpcCall,
@@ -145,6 +150,92 @@ export async function ipcGetVelayStatus(): Promise<VelayTunnelStatus | null> {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Webhook ingress route registry
+// ---------------------------------------------------------------------------
+
+/**
+ * Why a webhook-route call failed.
+ *
+ * `no_response` means nothing came back. The one-shot IPC transport answers a
+ * missing gateway and a gateway-side refusal the same way, with no result, so
+ * both land here. `invalid_response` means the gateway answered but the answer
+ * does not match the shared contract, so the two sides have drifted.
+ */
+export type WebhookRouteIpcFailureReason = "no_response" | "invalid_response";
+
+export type IpcRegisterWebhookRouteResult =
+  | { ok: true; disabled: true }
+  | { ok: true; disabled: false; route: WebhookIngressRoute }
+  | { ok: false; reason: WebhookRouteIpcFailureReason };
+
+export type IpcUnregisterWebhookRouteResult =
+  | { ok: true; removed: boolean }
+  | { ok: false; reason: WebhookRouteIpcFailureReason };
+
+export type IpcListWebhookRoutesResult =
+  | { ok: true; routes: WebhookIngressRoute[] }
+  | { ok: false; reason: WebhookRouteIpcFailureReason };
+
+function webhookRouteFailure(
+  method: string,
+  result: unknown,
+  detail: Record<string, unknown> = {},
+): { ok: false; reason: WebhookRouteIpcFailureReason } {
+  const reason: WebhookRouteIpcFailureReason =
+    result === undefined ? "no_response" : "invalid_response";
+  log.warn({ ...detail, result, reason }, `${method}: gateway call failed`);
+  return { ok: false, reason };
+}
+
+/**
+ * Claim a webhook subpath on the gateway.
+ *
+ * A `disabled` result is a normal answer, not a failure: the gateway is not
+ * serving its own webhooks and the caller should fall back to platform
+ * callback registration. A failure carries the reason it failed so a caller
+ * that also falls back can log the two apart.
+ */
+export async function ipcRegisterWebhookRoute(
+  input: RegisterWebhookRouteIpcParams,
+): Promise<IpcRegisterWebhookRouteResult> {
+  const result = await ipcCall("register_webhook_route", { ...input });
+  const parsed = RegisterWebhookRouteIpcResponseSchema.safeParse(result);
+  if (!parsed.success) {
+    return webhookRouteFailure("ipcRegisterWebhookRoute", result, {
+      path: input.path,
+    });
+  }
+  return parsed.data.disabled
+    ? { ok: true, disabled: true }
+    : { ok: true, disabled: false, route: parsed.data.route };
+}
+
+/**
+ * Drop a webhook subpath from the gateway registry. A successful call reports
+ * whether a route was actually removed.
+ */
+export async function ipcUnregisterWebhookRoute(
+  path: string,
+): Promise<IpcUnregisterWebhookRouteResult> {
+  const result = await ipcCall("unregister_webhook_route", { path });
+  const parsed = UnregisterWebhookRouteIpcResponseSchema.safeParse(result);
+  if (!parsed.success) {
+    return webhookRouteFailure("ipcUnregisterWebhookRoute", result, { path });
+  }
+  return { ok: true, removed: parsed.data.removed };
+}
+
+/** List every webhook subpath the gateway currently answers. */
+export async function ipcListWebhookRoutes(): Promise<IpcListWebhookRoutesResult> {
+  const result = await ipcCall("list_webhook_routes");
+  const parsed = ListWebhookRoutesIpcResponseSchema.safeParse(result);
+  if (!parsed.success) {
+    return webhookRouteFailure("ipcListWebhookRoutes", result);
+  }
+  return { ok: true, routes: parsed.data.routes };
+}
+
 // classify_risk is an idempotent, side-effect-free read, so a transient gateway
 // blip (socket dropped between calls, momentary unreachability) is safe to
 // retry — the persistent client re-establishes its socket on the next call. The

package/src/plugin-api/webhook-url.ts

@@ -16,6 +16,7 @@
 
 import { createHash } from "node:crypto";
 
+import { getIsPlatform } from "../config/env-registry.js";
 import { getConfig } from "../config/loader.js";
 import { resolveCallbackUrl } from "../inbound/platform-callback-registration.js";
 import { getPublicBaseUrl } from "../inbound/public-ingress-urls.js";
@@ -90,12 +91,11 @@ function registrationType(plugin: string, route: string): string {
 }
 
 /**
- * Keep a trailing slash on a resolved callback URL.
+ * Keep a trailing slash on a managed callback URL.
  *
  * Django in front of managed callbacks canonicalizes onto `/`. A vendor given
  * the slashless spelling is 301'd, and clients that follow a 301 on POST
- * typically retry as GET and drop the body. The gateway serves both spellings
- * of a plugin webhook, so the slashed URL is the one to hand out.
+ * typically retry as GET and drop the body.
  *
  * Query-bearing URLs are left alone: this resolver passes no query
  * parameters, and appending there would cut into the query rather than the
@@ -142,12 +142,26 @@ export async function resolveWebhookUrl(
 
   const callbackPath = `${PLUGIN_WEBHOOK_PREFIX}/${plugin}/${path}`;
 
+  let ingressUrl: string | undefined;
   const resolved = await resolveCallbackUrl(
-    () => `${getPublicBaseUrl(getConfig())}/${callbackPath}`,
+    () => {
+      ingressUrl = `${getPublicBaseUrl(getConfig())}/${callbackPath}`;
+      return ingressUrl;
+    },
     callbackPath,
     registrationType(plugin, path),
     undefined,
     sourceIdentifier,
   );
+
+  // A pod's ingress URL reaches the gateway through the tunnel, which forwards
+  // the request path verbatim and admits it only when it matches a claimed
+  // path byte for byte. The claim above is made under the slashless spelling,
+  // so that is the spelling to hand out. On a pod the supplier URL is only
+  // returned once its path is claimed, so this condition holds exactly for
+  // tunnel URLs; every other branch keeps the trailing slash.
+  if (getIsPlatform() && resolved === ingressUrl) {
+    return resolved;
+  }
   return withTrailingSlash(resolved);
 }

package/src/runtime/routes/__tests__/webhook-routes.test.ts

@@ -8,10 +8,13 @@ import { beforeEach, describe, expect, mock, test } from "bun:test";
 import { InternalError, UnprocessableEntityError } from "../errors.js";
 
 let isPlatform = false;
+let velayWebhooksEnabled = false;
 let config: Record<string, unknown> = {};
 let platformContextEnabled = false;
 let registerCallbackRouteError: Error | undefined;
 
+let localWebhookRouteRegistered = true;
+
 const registerCallbackRouteMock = mock(
   async (callbackPath: string, _type: string, _source?: string) => {
     if (registerCallbackRouteError) {
@@ -21,6 +24,11 @@ const registerCallbackRouteMock = mock(
   },
 );
 
+const registerLocalWebhookRouteMock = mock(
+  async (_callbackPath: string, _type: string, _source?: string) =>
+    localWebhookRouteRegistered,
+);
+
 // Spread the real modules: these are broad barrels and replacing them wholesale
 // breaks unrelated importers pulled in by the module under test.
 const actualEnvRegistry = await import("../../../config/env-registry.js");
@@ -35,8 +43,15 @@ mock.module("../../../config/loader.js", () => ({
   getConfig: () => config,
 }));
 
+const actualVelayGate = await import("../../../inbound/velay-webhooks-gate.js");
+mock.module("../../../inbound/velay-webhooks-gate.js", () => ({
+  ...actualVelayGate,
+  isVelayWebhooksEnabled: () => velayWebhooksEnabled,
+}));
+
 mock.module("../../../inbound/platform-callback-registration.js", () => ({
   registerCallbackRoute: registerCallbackRouteMock,
+  registerLocalWebhookRoute: registerLocalWebhookRouteMock,
   resolvePlatformCallbackRegistrationContext: async () => ({
     isPlatform,
     platformBaseUrl: "https://api.vellum.ai",
@@ -59,10 +74,13 @@ const register = (body: Record<string, unknown>) =>
 describe("webhooks_register callback URL resolution", () => {
   beforeEach(() => {
     isPlatform = false;
+    velayWebhooksEnabled = false;
     config = {};
     platformContextEnabled = false;
     registerCallbackRouteError = undefined;
+    localWebhookRouteRegistered = true;
     registerCallbackRouteMock.mockClear();
+    registerLocalWebhookRouteMock.mockClear();
   });
 
   test("platform pods register with the platform gateway", async () => {
@@ -75,6 +93,7 @@ describe("webhooks_register callback URL resolution", () => {
       path: "webhooks/telegram",
       mode: "platform",
     });
+    expect(registerLocalWebhookRouteMock).not.toHaveBeenCalled();
   });
 
   // The bug: a local assistant that IS connected to the platform used to fall
@@ -95,6 +114,68 @@ describe("webhooks_register callback URL resolution", () => {
     );
   });
 
+  test("velay-webhooks on: a pod claims the subpath and uses the published URL", async () => {
+    isPlatform = true;
+    velayWebhooksEnabled = true;
+    platformContextEnabled = true;
+    config = {
+      ingress: { publicBaseUrl: "https://velay.vellum.ai/assistant-123" },
+    };
+
+    expect(await register({ type: "telegram", source: "@my_bot" })).toEqual({
+      callbackUrl: "https://velay.vellum.ai/assistant-123/webhooks/telegram",
+      type: "telegram",
+      path: "webhooks/telegram",
+      mode: "self-hosted",
+    });
+    expect(registerLocalWebhookRouteMock).toHaveBeenCalledWith(
+      "webhooks/telegram",
+      "telegram",
+      "@my_bot",
+    );
+    expect(registerCallbackRouteMock).not.toHaveBeenCalled();
+  });
+
+  test("velay-webhooks on: a refused claim falls back to the platform", async () => {
+    isPlatform = true;
+    velayWebhooksEnabled = true;
+    platformContextEnabled = true;
+    localWebhookRouteRegistered = false;
+    config = {
+      ingress: { publicBaseUrl: "https://velay.vellum.ai/assistant-123" },
+    };
+
+    expect(await register({ type: "telegram" })).toMatchObject({
+      callbackUrl: "https://gateway.vellum.ai/assistant-123/webhooks/telegram",
+      mode: "platform",
+    });
+    expect(registerLocalWebhookRouteMock).toHaveBeenCalled();
+  });
+
+  test("velay-webhooks on: a pod with no published URL still registers with the platform", async () => {
+    isPlatform = true;
+    velayWebhooksEnabled = true;
+    platformContextEnabled = true;
+
+    expect(await register({ type: "telegram" })).toMatchObject({
+      callbackUrl: "https://gateway.vellum.ai/assistant-123/webhooks/telegram",
+      mode: "platform",
+    });
+    expect(registerLocalWebhookRouteMock).not.toHaveBeenCalled();
+  });
+
+  test("velay-webhooks on: a pod with ingress disabled falls back to the platform", async () => {
+    isPlatform = true;
+    velayWebhooksEnabled = true;
+    platformContextEnabled = true;
+    config = { ingress: { enabled: false } };
+
+    expect(await register({ type: "telegram" })).toMatchObject({
+      mode: "platform",
+    });
+    expect(registerLocalWebhookRouteMock).not.toHaveBeenCalled();
+  });
+
   test("disconnected local assistant uses the configured publicBaseUrl", async () => {
     config = { ingress: { publicBaseUrl: "https://abc.ngrok.io" } };
 
@@ -105,6 +186,7 @@ describe("webhooks_register callback URL resolution", () => {
       mode: "self-hosted",
     });
     expect(registerCallbackRouteMock).not.toHaveBeenCalled();
+    expect(registerLocalWebhookRouteMock).not.toHaveBeenCalled();
   });
 
   test("disconnected local assistant with no ingress is still unprocessable", async () => {
@@ -124,6 +206,7 @@ describe("webhooks_register callback URL resolution", () => {
       mode: "self-hosted",
     });
     expect(registerCallbackRouteMock).not.toHaveBeenCalled();
+    expect(registerLocalWebhookRouteMock).not.toHaveBeenCalled();
   });
 
   // The gateway publishes the Velay tunnel URL into ingress.publicBaseUrl, so

package/src/runtime/routes/webhook-routes.ts

@@ -15,12 +15,15 @@ import { getIsPlatform } from "../../config/env-registry.js";
 import { getConfig } from "../../config/loader.js";
 import {
   registerCallbackRoute,
+  registerLocalWebhookRoute,
   resolvePlatformCallbackRegistrationContext,
 } from "../../inbound/platform-callback-registration.js";
+import { resolveClaimedPodWebhookUrl } from "../../inbound/pod-webhook-claim.js";
 import {
   getPublicBaseUrl,
   isPublicIngressDisabled,
 } from "../../inbound/public-ingress-urls.js";
+import { isVelayWebhooksEnabled } from "../../inbound/velay-webhooks-gate.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import {
   BadRequestError,
@@ -109,8 +112,13 @@ async function registerWithPlatform(
  * Resolve a stable callback URL for a webhook type.
  *
  * Resolution order:
- *   1. **Platform pods** (`IS_PLATFORM`) always register with the platform
- *      gateway: they have no ingress of their own to advertise.
+ *   1. **Platform pods** (`IS_PLATFORM`) with the `velay-webhooks` flag off
+ *      always register with the platform gateway. With the flag on, the
+ *      Velay-published `ingress.publicBaseUrl` wins and platform
+ *      registration is the fallback for any failure to resolve it —
+ *      including an explicit `ingress.enabled: false`, matching
+ *      `resolveCallbackUrl`'s pod behavior. The subpath is claimed on the
+ *      gateway first, and a refused claim falls back the same way.
  *   2. **A configured public ingress wins** for everyone else. That URL is
  *      either the user's own tunnel (ngrok, a custom domain) or the Velay
  *      tunnel URL the gateway publishes into `ingress.publicBaseUrl`, so a
@@ -141,6 +149,20 @@ async function handleWebhooksRegister(
   const sourceIdentifier = source as string | undefined;
 
   if (getIsPlatform()) {
+    if (isVelayWebhooksEnabled()) {
+      const callbackUrl = await resolveClaimedPodWebhookUrl(
+        () => `${getPublicBaseUrl(getConfig())}/${webhookPath}`,
+        () => registerLocalWebhookRoute(webhookPath, type, sourceIdentifier),
+      );
+      if (callbackUrl !== undefined) {
+        return {
+          callbackUrl,
+          type,
+          path: webhookPath,
+          mode: "self-hosted",
+        };
+      }
+    }
     return registerWithPlatform(webhookPath, type, sourceIdentifier);
   }