fix: harden voice-call webhook verification

Author: steipete

CHANGELOG.md

@@ -15,6 +15,7 @@ Docs: https://docs.openclaw.ai
 - Web UI: resolve header logo path when `gateway.controlUi.basePath` is set. (#7178) Thanks @Yeom-JinHo.
 - Web UI: apply button styling to the new-messages indicator.
 - Security: keep untrusted channel metadata out of system prompts (Slack/Discord). Thanks @KonstantinMirin.
+- Voice call: harden webhook verification with host allowlists/proxy trust and keep ngrok loopback bypass.
 
 ## 2026.2.2-3
 

docs/platforms/fly.md

@@ -446,15 +446,18 @@ Example voice-call config with ngrok:
         "enabled": true,
         "config": {
           "provider": "twilio",
-          "tunnel": { "provider": "ngrok" }
+          "tunnel": { "provider": "ngrok" },
+          "webhookSecurity": {
+            "allowedHosts": ["example.ngrok.app"]
+          }
         }
       }
     }
   }
 }
 ```
 
-The ngrok tunnel runs inside the container and provides a public webhook URL without exposing the Fly app itself.
+The ngrok tunnel runs inside the container and provides a public webhook URL without exposing the Fly app itself. Set `webhookSecurity.allowedHosts` to the public tunnel hostname so forwarded host headers are accepted.
 
 ### Security benefits
 

docs/plugins/voice-call.md

@@ -81,6 +81,12 @@ Set config under `plugins.entries.voice-call.config`:
             path: "/voice/webhook",
           },
 
+          // Webhook security (recommended for tunnels/proxies)
+          webhookSecurity: {
+            allowedHosts: ["voice.example.com"],
+            trustedProxyIPs: ["100.64.0.1"],
+          },
+
           // Public exposure (pick one)
           // publicUrl: "https://example.ngrok.app/voice/webhook",
           // tunnel: { provider: "ngrok" },
@@ -111,6 +117,38 @@ Notes:
 - `tunnel.allowNgrokFreeTierLoopbackBypass: true` allows Twilio webhooks with invalid signatures **only** when `tunnel.provider="ngrok"` and `serve.bind` is loopback (ngrok local agent). Use for local dev only.
 - Ngrok free tier URLs can change or add interstitial behavior; if `publicUrl` drifts, Twilio signatures will fail. For production, prefer a stable domain or Tailscale funnel.
 
+## Webhook Security
+
+When a proxy or tunnel sits in front of the Gateway, the plugin reconstructs the
+public URL for signature verification. These options control which forwarded
+headers are trusted.
+
+`webhookSecurity.allowedHosts` allowlists hosts from forwarding headers.
+
+`webhookSecurity.trustForwardingHeaders` trusts forwarded headers without an allowlist.
+
+`webhookSecurity.trustedProxyIPs` only trusts forwarded headers when the request
+remote IP matches the list.
+
+Example with a stable public host:
+
+```json5
+{
+  plugins: {
+    entries: {
+      "voice-call": {
+        config: {
+          publicUrl: "https://voice.example.com/voice/webhook",
+          webhookSecurity: {
+            allowedHosts: ["voice.example.com"],
+          },
+        },
+      },
+    },
+  },
+}
+```
+
 ## TTS for calls
 
 Voice Call uses the core `messages.tts` configuration (OpenAI or ElevenLabs) for

extensions/voice-call/src/config.test.ts

@@ -17,6 +17,11 @@ function createBaseConfig(provider: "telnyx" | "twilio" | "plivo" | "mock"): Voi
     serve: { port: 3334, bind: "127.0.0.1", path: "/voice/webhook" },
     tailscale: { mode: "off", path: "/voice/webhook" },
     tunnel: { provider: "none", allowNgrokFreeTierLoopbackBypass: false },
+    webhookSecurity: {
+      allowedHosts: [],
+      trustForwardingHeaders: false,
+      trustedProxyIPs: [],
+    },
     streaming: {
       enabled: false,
       sttProvider: "openai-realtime",

extensions/voice-call/src/config.ts

@@ -211,16 +211,37 @@ export const VoiceCallTunnelConfigSchema = z
      * will be allowed only for loopback requests (ngrok local agent).
      */
     allowNgrokFreeTierLoopbackBypass: z.boolean().default(false),
-    /**
-     * Legacy ngrok free tier compatibility mode (deprecated).
-     * Use allowNgrokFreeTierLoopbackBypass instead.
-     */
-    allowNgrokFreeTier: z.boolean().optional(),
   })
   .strict()
   .default({ provider: "none", allowNgrokFreeTierLoopbackBypass: false });
 export type VoiceCallTunnelConfig = z.infer<typeof VoiceCallTunnelConfigSchema>;
 
+// -----------------------------------------------------------------------------
+// Webhook Security Configuration
+// -----------------------------------------------------------------------------
+
+export const VoiceCallWebhookSecurityConfigSchema = z
+  .object({
+    /**
+     * Allowed hostnames for webhook URL reconstruction.
+     * Only these hosts are accepted from forwarding headers.
+     */
+    allowedHosts: z.array(z.string().min(1)).default([]),
+    /**
+     * Trust X-Forwarded-* headers without a hostname allowlist.
+     * WARNING: Only enable if you trust your proxy configuration.
+     */
+    trustForwardingHeaders: z.boolean().default(false),
+    /**
+     * Trusted proxy IP addresses. Forwarded headers are only trusted when
+     * the remote IP matches one of these addresses.
+     */
+    trustedProxyIPs: z.array(z.string().min(1)).default([]),
+  })
+  .strict()
+  .default({ allowedHosts: [], trustForwardingHeaders: false, trustedProxyIPs: [] });
+export type WebhookSecurityConfig = z.infer<typeof VoiceCallWebhookSecurityConfigSchema>;
+
 // -----------------------------------------------------------------------------
 // Outbound Call Configuration
 // -----------------------------------------------------------------------------
@@ -339,6 +360,9 @@ export const VoiceCallConfigSchema = z
     /** Tunnel configuration (unified ngrok/tailscale) */
     tunnel: VoiceCallTunnelConfigSchema,
 
+    /** Webhook signature reconstruction and proxy trust configuration */
+    webhookSecurity: VoiceCallWebhookSecurityConfigSchema,
+
     /** Real-time audio streaming configuration */
     streaming: VoiceCallStreamingConfigSchema,
 
@@ -409,10 +433,21 @@ export function resolveVoiceCallConfig(config: VoiceCallConfig): VoiceCallConfig
     allowNgrokFreeTierLoopbackBypass: false,
   };
   resolved.tunnel.allowNgrokFreeTierLoopbackBypass =
-    resolved.tunnel.allowNgrokFreeTierLoopbackBypass || resolved.tunnel.allowNgrokFreeTier || false;
+    resolved.tunnel.allowNgrokFreeTierLoopbackBypass ?? false;
   resolved.tunnel.ngrokAuthToken = resolved.tunnel.ngrokAuthToken ?? process.env.NGROK_AUTHTOKEN;
   resolved.tunnel.ngrokDomain = resolved.tunnel.ngrokDomain ?? process.env.NGROK_DOMAIN;
 
+  // Webhook Security Config
+  resolved.webhookSecurity = resolved.webhookSecurity ?? {
+    allowedHosts: [],
+    trustForwardingHeaders: false,
+    trustedProxyIPs: [],
+  };
+  resolved.webhookSecurity.allowedHosts = resolved.webhookSecurity.allowedHosts ?? [];
+  resolved.webhookSecurity.trustForwardingHeaders =
+    resolved.webhookSecurity.trustForwardingHeaders ?? false;
+  resolved.webhookSecurity.trustedProxyIPs = resolved.webhookSecurity.trustedProxyIPs ?? [];
+
   return resolved;
 }
 

extensions/voice-call/src/providers/plivo.ts

@@ -1,5 +1,5 @@
 import crypto from "node:crypto";
-import type { PlivoConfig } from "../config.js";
+import type { PlivoConfig, WebhookSecurityConfig } from "../config.js";
 import type {
   HangupCallInput,
   InitiateCallInput,
@@ -23,6 +23,8 @@ export interface PlivoProviderOptions {
   skipVerification?: boolean;
   /** Outbound ring timeout in seconds */
   ringTimeoutSec?: number;
+  /** Webhook security options (forwarded headers/allowlist) */
+  webhookSecurity?: WebhookSecurityConfig;
 }
 
 type PendingSpeak = { text: string; locale?: string };
@@ -92,6 +94,10 @@ export class PlivoProvider implements VoiceCallProvider {
     const result = verifyPlivoWebhook(ctx, this.authToken, {
       publicUrl: this.options.publicUrl,
       skipVerification: this.options.skipVerification,
+      allowedHosts: this.options.webhookSecurity?.allowedHosts,
+      trustForwardingHeaders: this.options.webhookSecurity?.trustForwardingHeaders,
+      trustedProxyIPs: this.options.webhookSecurity?.trustedProxyIPs,
+      remoteIP: ctx.remoteAddress,
     });
 
     if (!result.ok) {
@@ -112,7 +118,7 @@ export class PlivoProvider implements VoiceCallProvider {
     // Keep providerCallId mapping for later call control.
     const callUuid = parsed.get("CallUUID") || undefined;
     if (callUuid) {
-      const webhookBase = PlivoProvider.baseWebhookUrlFromCtx(ctx);
+      const webhookBase = this.baseWebhookUrlFromCtx(ctx);
       if (webhookBase) {
         this.callUuidToWebhookUrl.set(callUuid, webhookBase);
       }
@@ -444,7 +450,7 @@ export class PlivoProvider implements VoiceCallProvider {
     ctx: WebhookContext,
     opts: { flow: string; callId?: string },
   ): string | null {
-    const base = PlivoProvider.baseWebhookUrlFromCtx(ctx);
+    const base = this.baseWebhookUrlFromCtx(ctx);
     if (!base) {
       return null;
     }
@@ -458,9 +464,16 @@ export class PlivoProvider implements VoiceCallProvider {
     return u.toString();
   }
 
-  private static baseWebhookUrlFromCtx(ctx: WebhookContext): string | null {
+  private baseWebhookUrlFromCtx(ctx: WebhookContext): string | null {
     try {
-      const u = new URL(reconstructWebhookUrl(ctx));
+      const u = new URL(
+        reconstructWebhookUrl(ctx, {
+          allowedHosts: this.options.webhookSecurity?.allowedHosts,
+          trustForwardingHeaders: this.options.webhookSecurity?.trustForwardingHeaders,
+          trustedProxyIPs: this.options.webhookSecurity?.trustedProxyIPs,
+          remoteIP: ctx.remoteAddress,
+        }),
+      );
       return `${u.origin}${u.pathname}`;
     } catch {
       return null;

extensions/voice-call/src/providers/twilio.ts

@@ -1,5 +1,5 @@
 import crypto from "node:crypto";
-import type { TwilioConfig } from "../config.js";
+import type { TwilioConfig, WebhookSecurityConfig } from "../config.js";
 import type { MediaStreamHandler } from "../media-stream.js";
 import type { TelephonyTtsProvider } from "../telephony-tts.js";
 import type {
@@ -38,6 +38,8 @@ export interface TwilioProviderOptions {
   streamPath?: string;
   /** Skip webhook signature verification (development only) */
   skipVerification?: boolean;
+  /** Webhook security options (forwarded headers/allowlist) */
+  webhookSecurity?: WebhookSecurityConfig;
 }
 
 export class TwilioProvider implements VoiceCallProvider {

extensions/voice-call/src/providers/twilio/webhook.ts

@@ -12,6 +12,10 @@ export function verifyTwilioProviderWebhook(params: {
     publicUrl: params.currentPublicUrl || undefined,
     allowNgrokFreeTierLoopbackBypass: params.options.allowNgrokFreeTierLoopbackBypass ?? false,
     skipVerification: params.options.skipVerification,
+    allowedHosts: params.options.webhookSecurity?.allowedHosts,
+    trustForwardingHeaders: params.options.webhookSecurity?.trustForwardingHeaders,
+    trustedProxyIPs: params.options.webhookSecurity?.trustedProxyIPs,
+    remoteIP: params.ctx.remoteAddress,
   });
 
   if (!result.ok) {

extensions/voice-call/src/runtime.ts

@@ -44,7 +44,7 @@ function resolveProvider(config: VoiceCallConfig): VoiceCallProvider {
   const allowNgrokFreeTierLoopbackBypass =
     config.tunnel?.provider === "ngrok" &&
     isLoopbackBind(config.serve?.bind) &&
-    (config.tunnel?.allowNgrokFreeTierLoopbackBypass || config.tunnel?.allowNgrokFreeTier || false);
+    (config.tunnel?.allowNgrokFreeTierLoopbackBypass ?? false);
 
   switch (config.provider) {
     case "telnyx":
@@ -70,6 +70,7 @@ function resolveProvider(config: VoiceCallConfig): VoiceCallProvider {
           publicUrl: config.publicUrl,
           skipVerification: config.skipSignatureVerification,
           streamPath: config.streaming?.enabled ? config.streaming.streamPath : undefined,
+          webhookSecurity: config.webhookSecurity,
         },
       );
     case "plivo":
@@ -82,6 +83,7 @@ function resolveProvider(config: VoiceCallConfig): VoiceCallProvider {
           publicUrl: config.publicUrl,
           skipVerification: config.skipSignatureVerification,
           ringTimeoutSec: Math.max(1, Math.floor(config.ringTimeoutMs / 1000)),
+          webhookSecurity: config.webhookSecurity,
         },
       );
     case "mock":