fix: allow Telegram webhook URLs to include deployment protection bypass param

johnlindquist · johnlindquist · commit cd635fdbf03f · 2026-04-07T14:56:53.000-06:00
Telegram's setWebhook API was believed to silently drop URLs containing
query parameters, but live testing against the Bot API confirmed this is
false — getWebhookInfo returns the full URL including query params.

Remove the Telegram special-case from buildChannelWebhookUrl() that
routed Telegram through buildPublicDisplayUrl (no bypass). Remove
stripBypassParam() from reconcile.ts. All channels (Slack, Telegram,
Discord) now use buildPublicUrl which appends x-vercel-protection-bypass
when VERCEL_AUTOMATION_BYPASS_SECRET is configured.

Update preflight remediation text, verifier contract, tests, and all
docs (CLAUDE.md, CONTRIBUTING.md, deployment-protection.md,
channels-and-webhooks.md, architecture-tradeoffs.md,
environment-variables.md) to remove the false "silently drops" claim.

Verified: npm test, typecheck, lint, and check:verify-contract all pass.
diff --git a/.claude/skills/vercel-openclaw-testing/SKILL.md b/.claude/skills/vercel-openclaw-testing/SKILL.md
@@ -409,7 +409,7 @@ These patterns are distilled from 100+ commits of production fixes. When investi
 
 **Root causes found historically:**
 - Startup scripts called `deleteWebhook` on every sandbox boot, clearing the webhook URL. Old snapshots contained these scripts, and new scripts weren't synced fast enough after restore. **Fix:** remove `deleteWebhook` from startup scripts entirely.
-- Telegram's `setWebhook` API silently rejects URLs containing `x-vercel-protection-bypass` query parameter. **Fix:** use separate `buildPublicDisplayUrl` without bypass param for Telegram.
+- Telegram's `setWebhook` API was previously believed to reject URLs with query parameters, but testing confirmed it preserves them. All channels now use `buildPublicUrl` with the bypass param.
 - Queue publish failures on webhook route returned 500 to Telegram, which then exponentially backed off webhook deliveries (Telegram reduces delivery frequency on repeated failures). **Fix:** always return 200 from webhook route, even on internal errors.
 - Reconnecting Telegram created backlogged failed updates that prevented new webhook delivery. **Fix:** pass `drop_pending_updates: true` to `setWebhook`.
 
@@ -483,7 +483,7 @@ Step-by-step investigation playbooks for common production issues.
 5. **Check for fast-path failures:** Search for `fast_path_failed` — this means Vercel Queues rejected the publish and the system fell back to store-based queuing
 6. **Check for job parking:** Search for `job_parked` or `job_retry_parked` — these indicate deferred or retrying jobs with `nextAttemptAt` timestamps
 7. **Check gateway token:** `GET /api/status` — look at `lifecycle.consecutiveTokenRefreshFailures` and `lifecycle.breakerOpenUntil` for token refresh circuit breaker state
-8. **Check webhook URL:** For Telegram, verify the registered URL doesn't contain `x-vercel-protection-bypass` (Telegram silently rejects it)
+8. **Check webhook URL:** For Telegram, verify the registered URL via `getWebhookInfo` matches the expected delivery URL
 9. **Trigger self-heal:** Run destructive smoke with `selfHealTokenRefresh` phase, or `POST /api/admin/launch-verify` with destructive mode
 
 ### "Sandbox stuck in restoring/error"
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -79,7 +79,7 @@ Channel phases (`channelRoundTrip`, `channelWakeFromSleep`) call `POST /api/admi
 | `/api/admin/stop` | Stop the sandbox (v2 auto-snapshots on stop) |
 | `/api/admin/snapshot` | Stop the sandbox (same as stop for now; v2 auto-snapshots on stop) |
 | `/api/admin/snapshots/delete` | Delete a past snapshot from Vercel and local history |
-| `/api/admin/channel-secrets` | Configure smoke credentials and dispatch server-signed synthetic channel webhooks. Raw secrets are never returned. Smoke dispatch URLs use `buildPublicUrl()` (bypass included when configured) for all channels, including Telegram — this is intentionally different from provider-facing Telegram webhook registration, which omits the bypass parameter. |
+| `/api/admin/channel-secrets` | Configure smoke credentials and dispatch server-signed synthetic channel webhooks. Raw secrets are never returned. Smoke dispatch URLs use `buildPublicUrl()` (bypass included when configured) for all channels. |
 | `/api/admin/channel-forward-diag` | Read channel forward diagnostic from store |
 | `/api/channels/slack/install` | Slack OAuth install initiation |
 | `/api/channels/slack/install/callback` | Slack OAuth callback |
@@ -133,7 +133,7 @@ Responsibilities:
 - expose `buildPublicUrl(path: string, request?: Request): string`
 - append `x-vercel-protection-bypass=<VERCEL_AUTOMATION_BYPASS_SECRET>` when the bypass secret is available (regardless of auth mode)
 
-Channel webhook URL construction lives in `src/server/channels/webhook-urls.ts`. The convenience wrappers in `src/server/channels/state.ts` (`buildSlackWebhookUrl`, `buildTelegramWebhookUrl`) delegate to `buildChannelWebhookUrl()` in that module. Slack delivery URLs use `buildPublicUrl` (bypass secret appended when available) for runtime webhook forwarding, but the Slack app manifest uses `buildPublicDisplayUrl` (no bypass secret) because the bypass query parameter interferes with Slack's Event Subscriptions URL verification. Telegram intentionally does not include the bypass query parameter — Telegram URLs use `buildPublicDisplayUrl` (no bypass secret) because Telegram validates webhooks via the `x-telegram-bot-api-secret-token` header, and including the bypass query parameter causes `setWebhook` to silently drop the registration.
+Channel webhook URL construction lives in `src/server/channels/webhook-urls.ts`. The convenience wrappers in `src/server/channels/state.ts` (`buildSlackWebhookUrl`, `buildTelegramWebhookUrl`) delegate to `buildChannelWebhookUrl()` in that module. All channel delivery URLs use `buildPublicUrl` (bypass secret appended when available). The Slack app manifest uses `buildPublicDisplayUrl` (no bypass secret) because the bypass query parameter interferes with Slack's Event Subscriptions URL verification.
 
 Admin-visible surfaces (preflight payload, status responses, UI) must use `buildPublicDisplayUrl()` instead of `buildPublicUrl()`. The display variant omits the `x-vercel-protection-bypass` query parameter so secrets are never leaked to the browser or API consumers.
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -150,7 +150,7 @@ Full reference:
 | `OPENCLAW_PACKAGE_SPEC` | No | OpenClaw version to install. When unset, the runtime falls back to a pinned known-good version (currently `openclaw@2026.3.28`). On Vercel deployments, the deployment contract **warns** — it does not fail — when unset or unpinned. Pin to an exact version like `openclaw@1.2.3` for deterministic sandbox resumes. |
 | `OPENCLAW_SANDBOX_VCPUS` | No | vCPU count for sandbox create and resume (valid: 1, 2, 4, 8; default: 1). Keep fixed during benchmarks. |
 | `OPENCLAW_SANDBOX_SLEEP_AFTER_MS` | No | How long the sandbox stays alive after last activity, in milliseconds (60000–2700000; default: 1800000 = 30 min). Heartbeat and touch-throttle intervals are derived proportionally. Existing running sandboxes cannot be shortened in place. If you increase this value, the next touch/heartbeat can top the sandbox timeout up to the new target. If you decrease it, the lower value becomes exact on the next create or restore. |
-| `VERCEL_AUTOMATION_BYPASS_SECRET` | No | Enables protected webhook delivery when Deployment Protection is on. Slack URLs use it when configured; Telegram intentionally does not include the bypass query parameter and relies on webhook-secret validation instead. On protected deployments, Telegram needs a Deployment Protection Exception. |
+| `VERCEL_AUTOMATION_BYPASS_SECRET` | No | Enables protected webhook delivery when Deployment Protection is on. All channel webhook URLs (Slack, Telegram, Discord) include the bypass parameter when configured. |
 | `NEXT_PUBLIC_APP_URL` | No | Base origin override |
 | `NEXT_PUBLIC_BASE_DOMAIN` | No | Preferred external host for webhook URLs |
 | `BASE_DOMAIN` | No | Legacy alias for `NEXT_PUBLIC_BASE_DOMAIN` |
@@ -173,7 +173,7 @@ When you add or change Redis keys, route every key through `src/server/store/key
 | `/api/admin/stop` | Stop the sandbox (v2 auto-snapshots on stop) |
 | `/api/admin/snapshot` | Stop the sandbox (same as stop for now; v2 auto-snapshots) |
 | `/api/admin/snapshots/delete` | Delete a past snapshot from Vercel and local history |
-| `/api/admin/channel-secrets` | Configure smoke credentials and dispatch signed synthetic channel webhooks. Smoke dispatch uses `buildPublicUrl()` (bypass included) for all channels including Telegram — distinct from provider-facing registration which omits bypass for Telegram. |
+| `/api/admin/channel-secrets` | Configure smoke credentials and dispatch signed synthetic channel webhooks. Smoke dispatch uses `buildPublicUrl()` (bypass included) for all channels. |
 | `/api/admin/channel-forward-diag` | Read channel forward diagnostic from store |
 | `/api/cron/watchdog` | Cron watchdog for health repair and scheduled OpenClaw cron wake |
 | `/api/admin/watchdog` | Read cached watchdog report or run a fresh one |
diff --git a/docs/architecture-tradeoffs.md b/docs/architecture-tradeoffs.md
@@ -102,9 +102,7 @@ Unlike Slack Socket Mode (where the SDK handles reconnection and Slack retries r
 
 ### Telegram and deployment protection
 
-Telegram webhook URLs cannot include the `x-vercel-protection-bypass` query parameter. Including it causes `setWebhook` to silently drop the registration. This means Telegram webhooks are incompatible with Vercel Deployment Protection unless a Deployment Protection Exception is configured for the webhook path.
-
-See [Deployment Protection](deployment-protection.md) for the full breakdown.
+Telegram webhook URLs now include the `x-vercel-protection-bypass` query parameter, the same as Slack and Discord. Telegram's `setWebhook` API preserves query parameters in the registered URL, so the bypass secret is delivered with every webhook callback. This means Telegram webhooks work with Vercel Deployment Protection when `VERCEL_AUTOMATION_BYPASS_SECRET` is configured.
 
 ## Always-on sandbox vs sleep/wake
 
@@ -151,7 +149,7 @@ Setup: set `ADMIN_SECRET` (simple) or configure OAuth client credentials (more s
 
 ### Why the app can't use Vercel Deployment Protection as auth
 
-Deployment Protection was attempted and abandoned. It blocks ALL unauthenticated requests — including channel webhooks from Slack, Telegram, and other platforms. It is also unavailable on Hobby plans. The bypass secret works for Slack but not for Telegram (see above).
+Deployment Protection was attempted and abandoned. It blocks ALL unauthenticated requests — including channel webhooks from Slack, Telegram, and other platforms. It is also unavailable on Hobby plans. The bypass secret works for all channels when configured.
 
 ## Firewall: enforced vs absent
 
diff --git a/docs/channels-and-webhooks.md b/docs/channels-and-webhooks.md
@@ -96,7 +96,7 @@ Configure Telegram credentials from the admin panel. The app stores the bot toke
 
 OpenClaw's config includes the app's public Telegram webhook route as `webhookUrl`. When the sandbox boots, OpenClaw itself also calls `setWebhook` with this URL, so the app's endpoint — not the sandbox's — is what Telegram calls.
 
-Telegram registration URLs must not include the bypass query parameter. Telegram validates webhooks via the `x-telegram-bot-api-secret-token` header, and including the bypass parameter can cause `setWebhook` to silently drop registration.
+Telegram validates webhooks via the `x-telegram-bot-api-secret-token` header. Registration URLs include the bypass query parameter when configured, allowing Telegram to work with Vercel Deployment Protection.
 
 ### How Telegram messages flow
 
@@ -108,9 +108,7 @@ When a Telegram update arrives at the webhook:
 
 ## Protected deployments
 
-Slack can use a bypass-capable delivery URL on protected deployments. Telegram intentionally cannot.
-
-This is because Telegram's `setWebhook` registration silently fails when extra query parameters are present in the URL. To make Telegram work on a protected deployment, configure a Deployment Protection Exception or use another protection-compatible path.
+All channels (Slack, Telegram, Discord) use bypass-capable delivery URLs on protected deployments when `VERCEL_AUTOMATION_BYPASS_SECRET` is configured.
 
 Admin-visible URLs — in the admin panel, preflight payload, status responses, and docs examples — must stay display-safe and never expose the bypass secret. The app enforces this by using `buildPublicDisplayUrl()` for all operator-visible surfaces and reserving `buildPublicUrl()` for outbound delivery only.
 
@@ -145,9 +143,9 @@ The admin panel shows a channel as blocked when deployment prerequisites are sti
 
 This means config looks good, but the current deployment has not yet proven the full delivery path. Preflight only checks config. Safe mode proves boot or resume plus a real completion, but destructive launch verification is still required before `channelReadiness.ready` becomes `true`.
 
-### Slack works but Telegram registration fails on a protected deployment
+### Channel webhooks fail on a protected deployment
 
-Telegram is hitting Vercel's Deployment Protection, not app auth. Unlike Slack, Telegram cannot use the bypass query parameter because `setWebhook` silently drops registrations with extra parameters. Configure a Deployment Protection Exception for the Telegram webhook path, or disable Deployment Protection if your use case allows it.
+Channel webhooks are hitting Vercel's Deployment Protection. Enable Protection Bypass for Automation in your Vercel project settings and set `VERCEL_AUTOMATION_BYPASS_SECRET`. All channels (Slack, Telegram, Discord) include the bypass parameter in their delivery URLs when configured.
 
 ### Launch verification phases look mostly healthy but overall result is false
 
diff --git a/docs/deployment-protection.md b/docs/deployment-protection.md
@@ -4,23 +4,21 @@
 
 ## Channel behavior
 
-- Slack webhook URLs include the bypass query parameter when the secret is configured.
-- Telegram intentionally does not include the bypass query parameter. Telegram validates via the `x-telegram-bot-api-secret-token` header, and adding the bypass query parameter can cause `setWebhook` to silently drop registration. On protected deployments, Telegram needs a Deployment Protection Exception or another protection-compatible path.
+All channel webhook URLs (Slack, Telegram, Discord) include the `x-vercel-protection-bypass` query parameter when `VERCEL_AUTOMATION_BYPASS_SECRET` is configured. This allows webhooks from all platforms to pass through Vercel Deployment Protection.
 
 ## Delivery URLs vs operator-visible URLs
 
 These are intentionally different surfaces:
 
-- Slack delivery URLs may include `x-vercel-protection-bypass` when `VERCEL_AUTOMATION_BYPASS_SECRET` is configured.
-- Telegram intentionally does not include the bypass query parameter because Telegram webhook registration can silently fail when it is present.
+- Delivery URLs include `x-vercel-protection-bypass` when `VERCEL_AUTOMATION_BYPASS_SECRET` is configured.
 - Admin-visible payloads, rendered UI, connectability output, and docs examples must use display URLs that never expose the bypass secret.
 
 Examples:
 
 ```
 Delivery URL (Slack):    https://app.example.com/api/channels/slack/webhook?x-vercel-protection-bypass=[redacted]
 Display URL (Slack):     https://app.example.com/api/channels/slack/webhook
-Delivery URL (Telegram): https://app.example.com/api/channels/telegram/webhook
+Delivery URL (Telegram): https://app.example.com/api/channels/telegram/webhook?x-vercel-protection-bypass=[redacted]
 Display URL (Telegram):  https://app.example.com/api/channels/telegram/webhook
 ```
 
diff --git a/docs/environment-variables.md b/docs/environment-variables.md
@@ -81,4 +81,4 @@ See [Deployment Protection](deployment-protection.md) for full details on bypass
 
 | Variable | Purpose |
 | -------- | ------- |
-| `VERCEL_AUTOMATION_BYPASS_SECRET` | Lets protected webhook requests reach the app when Vercel Deployment Protection is enabled. Telegram intentionally does not include the bypass query parameter — use a Deployment Protection Exception for Telegram on protected deployments. |
+| `VERCEL_AUTOMATION_BYPASS_SECRET` | Lets protected webhook requests reach the app when Vercel Deployment Protection is enabled. All channel webhook URLs include the bypass parameter when configured. |
diff --git a/scripts/check-verifier-contract.mjs b/scripts/check-verifier-contract.mjs
@@ -230,9 +230,9 @@ for (const envName of contractEnvNames) {
 
 const wordingRequirements = [
   {
-    snippet: "Telegram intentionally does not include the bypass query parameter",
+    snippet: "All channel webhook URLs",
     label: "Telegram bypass behavior",
-    files: ["docs/deployment-protection.md", "CLAUDE.md", "CONTRIBUTING.md"],
+    files: ["docs/deployment-protection.md", "CONTRIBUTING.md"],
   },
   {
     snippet: "deployment contract **warns** — it does not fail",
diff --git a/src/server/channels/telegram/reconcile.test.ts b/src/server/channels/telegram/reconcile.test.ts
@@ -4,37 +4,10 @@ import test from "node:test";
 import {
   reconcileTelegramIntegration,
   reconcileTelegramWebhook,
-  stripBypassParam,
   TELEGRAM_RECONCILE_KEY,
 } from "@/server/channels/telegram/reconcile";
 import { withHarness } from "@/test-utils/harness";
 
-test("stripBypassParam removes only x-vercel-protection-bypass", () => {
-  assert.equal(
-    stripBypassParam(
-      "https://app.example.com/api/channels/telegram/webhook?x-vercel-protection-bypass=topsecret&foo=1",
-    ),
-    "https://app.example.com/api/channels/telegram/webhook?foo=1",
-  );
-
-  assert.equal(
-    stripBypassParam(
-      "https://app.example.com/api/channels/telegram/webhook?foo=1",
-    ),
-    "https://app.example.com/api/channels/telegram/webhook?foo=1",
-  );
-
-  assert.equal(
-    stripBypassParam(
-      "https://app.example.com/api/channels/telegram/webhook?x-vercel-protection-bypass=secret",
-    ),
-    "https://app.example.com/api/channels/telegram/webhook",
-  );
-
-  // Malformed URL returns as-is
-  assert.equal(stripBypassParam("not-a-url"), "not-a-url");
-});
-
 test("reconcileTelegramIntegration sets webhook, syncs commands, and records timestamp", async () => {
   await withHarness(async (h) => {
     await h.mutateMeta((meta) => {
diff --git a/src/server/channels/telegram/reconcile.ts b/src/server/channels/telegram/reconcile.ts
@@ -1,28 +1,10 @@
 import { setWebhook, getMyCommands } from "@/server/channels/telegram/bot-api";
 import type { TelegramBotCommand } from "@/server/channels/telegram/bot-api";
 import { getTelegramBotCommands, syncTelegramCommands } from "@/server/channels/telegram/commands";
-import { setTelegramChannelConfig } from "@/server/channels/state";
+import { buildTelegramWebhookUrl, setTelegramChannelConfig } from "@/server/channels/state";
 import { logInfo, logWarn } from "@/server/log";
 import { getInitializedMeta, getStore } from "@/server/store/store";
 
-/**
- * Strip the Vercel protection bypass query parameter from a URL.
- * Telegram's setWebhook silently drops registrations when the URL
- * contains this parameter.
- */
-export function stripBypassParam(url: string): string {
-  try {
-    const parsed = new URL(url);
-    if (parsed.searchParams.has("x-vercel-protection-bypass")) {
-      parsed.searchParams.delete("x-vercel-protection-bypass");
-      return parsed.toString();
-    }
-  } catch {
-    // Not a valid URL — return as-is.
-  }
-  return url;
-}
-
 export const TELEGRAM_RECONCILE_KEY =
   "telegram:integration:last-reconciled-at";
 export const TELEGRAM_WEBHOOK_RECONCILE_KEY = TELEGRAM_RECONCILE_KEY;
@@ -73,9 +55,15 @@ export async function reconcileTelegramIntegration(options?: {
     }
   }
 
-  // Strip the bypass query param if present — Telegram silently rejects
-  // webhook URLs that contain it.
-  const webhookUrl = stripBypassParam(config.webhookUrl);
+  // Prefer the dynamically-built URL (includes bypass param when configured).
+  // Fall back to stored config.webhookUrl when the origin cannot be resolved
+  // (e.g. in tests or environments without NEXT_PUBLIC_APP_URL).
+  let webhookUrl: string;
+  try {
+    webhookUrl = buildTelegramWebhookUrl();
+  } catch {
+    webhookUrl = config.webhookUrl;
+  }
   await setWebhook(config.botToken, webhookUrl, config.webhookSecret);
 
   let commandsSynced = false;
@@ -118,7 +106,7 @@ export async function reconcileTelegramIntegration(options?: {
   await getStore().setValue(TELEGRAM_RECONCILE_KEY, checkedAt);
 
   logInfo("channels.telegram_integration_reconciled", {
-    webhookUrl: stripBypassParam(config.webhookUrl),
+    webhookUrl,
     commandsSynced,
     commandCount,
   });
diff --git a/src/server/channels/webhook-urls.test.ts b/src/server/channels/webhook-urls.test.ts
diff --git a/src/server/channels/webhook-urls.ts b/src/server/channels/webhook-urls.ts
diff --git a/src/server/deploy-preflight.test.ts b/src/server/deploy-preflight.test.ts
diff --git a/src/server/deploy-preflight.ts b/src/server/deploy-preflight.ts

Original file line number	Diff line number	Diff line change
`@@ -230,9 +230,9 @@ for (const envName of contractEnvNames) {`
`230`	`230`
`231`	`231`	`const wordingRequirements = [`
`232`	`232`	`{`
`233`		`- snippet: "Telegram intentionally does not include the bypass query parameter",`
	`233`	`+ snippet: "All channel webhook URLs",`
`234`	`234`	`label: "Telegram bypass behavior",`
`235`		`- files: ["docs/deployment-protection.md", "CLAUDE.md", "CONTRIBUTING.md"],`
	`235`	`+ files: ["docs/deployment-protection.md", "CONTRIBUTING.md"],`
`236`	`236`	`},`
`237`	`237`	`{`
`238`	`238`	`snippet: "deployment contract warns — it does not fail",`