@clawdbot/voice-call 2026.1.16 → 2026.1.20

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 2026.1.20
+
+### Changes
+- Version alignment with core Clawdbot release numbers.
+
+## 2026.1.17-1
+
+### Changes
+- Version alignment with core Clawdbot release numbers.
+
+## 2026.1.17
+
+### Changes
+- Version alignment with core Clawdbot release numbers.
+
 ## 2026.1.16
 
 ### Changes

package/clawdbot.plugin.json

@@ -0,0 +1,405 @@
+{
+  "id": "voice-call",
+  "uiHints": {
+    "provider": {
+      "label": "Provider",
+      "help": "Use twilio, telnyx, or mock for dev/no-network."
+    },
+    "fromNumber": {
+      "label": "From Number",
+      "placeholder": "+15550001234"
+    },
+    "toNumber": {
+      "label": "Default To Number",
+      "placeholder": "+15550001234"
+    },
+    "inboundPolicy": {
+      "label": "Inbound Policy"
+    },
+    "allowFrom": {
+      "label": "Inbound Allowlist"
+    },
+    "inboundGreeting": {
+      "label": "Inbound Greeting",
+      "advanced": true
+    },
+    "telnyx.apiKey": {
+      "label": "Telnyx API Key",
+      "sensitive": true
+    },
+    "telnyx.connectionId": {
+      "label": "Telnyx Connection ID"
+    },
+    "telnyx.publicKey": {
+      "label": "Telnyx Public Key",
+      "sensitive": true
+    },
+    "twilio.accountSid": {
+      "label": "Twilio Account SID"
+    },
+    "twilio.authToken": {
+      "label": "Twilio Auth Token",
+      "sensitive": true
+    },
+    "outbound.defaultMode": {
+      "label": "Default Call Mode"
+    },
+    "outbound.notifyHangupDelaySec": {
+      "label": "Notify Hangup Delay (sec)",
+      "advanced": true
+    },
+    "serve.port": {
+      "label": "Webhook Port"
+    },
+    "serve.bind": {
+      "label": "Webhook Bind"
+    },
+    "serve.path": {
+      "label": "Webhook Path"
+    },
+    "tailscale.mode": {
+      "label": "Tailscale Mode",
+      "advanced": true
+    },
+    "tailscale.path": {
+      "label": "Tailscale Path",
+      "advanced": true
+    },
+    "tunnel.provider": {
+      "label": "Tunnel Provider",
+      "advanced": true
+    },
+    "tunnel.ngrokAuthToken": {
+      "label": "ngrok Auth Token",
+      "sensitive": true,
+      "advanced": true
+    },
+    "tunnel.ngrokDomain": {
+      "label": "ngrok Domain",
+      "advanced": true
+    },
+    "tunnel.allowNgrokFreeTier": {
+      "label": "Allow ngrok Free Tier",
+      "advanced": true
+    },
+    "streaming.enabled": {
+      "label": "Enable Streaming",
+      "advanced": true
+    },
+    "streaming.openaiApiKey": {
+      "label": "OpenAI Realtime API Key",
+      "sensitive": true,
+      "advanced": true
+    },
+    "streaming.sttModel": {
+      "label": "Realtime STT Model",
+      "advanced": true
+    },
+    "streaming.streamPath": {
+      "label": "Media Stream Path",
+      "advanced": true
+    },
+    "tts.model": {
+      "label": "TTS Model",
+      "advanced": true
+    },
+    "tts.voice": {
+      "label": "TTS Voice",
+      "advanced": true
+    },
+    "tts.instructions": {
+      "label": "TTS Instructions",
+      "advanced": true
+    },
+    "publicUrl": {
+      "label": "Public Webhook URL",
+      "advanced": true
+    },
+    "skipSignatureVerification": {
+      "label": "Skip Signature Verification",
+      "advanced": true
+    },
+    "store": {
+      "label": "Call Log Store Path",
+      "advanced": true
+    },
+    "responseModel": {
+      "label": "Response Model",
+      "advanced": true
+    },
+    "responseSystemPrompt": {
+      "label": "Response System Prompt",
+      "advanced": true
+    },
+    "responseTimeoutMs": {
+      "label": "Response Timeout (ms)",
+      "advanced": true
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean"
+      },
+      "provider": {
+        "type": "string",
+        "enum": [
+          "telnyx",
+          "twilio",
+          "plivo",
+          "mock"
+        ]
+      },
+      "telnyx": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "apiKey": {
+            "type": "string"
+          },
+          "connectionId": {
+            "type": "string"
+          },
+          "publicKey": {
+            "type": "string"
+          }
+        }
+      },
+      "twilio": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "accountSid": {
+            "type": "string"
+          },
+          "authToken": {
+            "type": "string"
+          }
+        }
+      },
+      "plivo": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "authId": {
+            "type": "string"
+          },
+          "authToken": {
+            "type": "string"
+          }
+        }
+      },
+      "fromNumber": {
+        "type": "string",
+        "pattern": "^\\+[1-9]\\d{1,14}$"
+      },
+      "toNumber": {
+        "type": "string",
+        "pattern": "^\\+[1-9]\\d{1,14}$"
+      },
+      "inboundPolicy": {
+        "type": "string",
+        "enum": [
+          "disabled",
+          "allowlist",
+          "pairing",
+          "open"
+        ]
+      },
+      "allowFrom": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "pattern": "^\\+[1-9]\\d{1,14}$"
+        }
+      },
+      "inboundGreeting": {
+        "type": "string"
+      },
+      "outbound": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "defaultMode": {
+            "type": "string",
+            "enum": [
+              "notify",
+              "conversation"
+            ]
+          },
+          "notifyHangupDelaySec": {
+            "type": "integer",
+            "minimum": 0
+          }
+        }
+      },
+      "maxDurationSeconds": {
+        "type": "integer",
+        "minimum": 1
+      },
+      "silenceTimeoutMs": {
+        "type": "integer",
+        "minimum": 1
+      },
+      "transcriptTimeoutMs": {
+        "type": "integer",
+        "minimum": 1
+      },
+      "ringTimeoutMs": {
+        "type": "integer",
+        "minimum": 1
+      },
+      "maxConcurrentCalls": {
+        "type": "integer",
+        "minimum": 1
+      },
+      "serve": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "port": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "bind": {
+            "type": "string"
+          },
+          "path": {
+            "type": "string"
+          }
+        }
+      },
+      "tailscale": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "mode": {
+            "type": "string",
+            "enum": [
+              "off",
+              "serve",
+              "funnel"
+            ]
+          },
+          "path": {
+            "type": "string"
+          }
+        }
+      },
+      "tunnel": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "provider": {
+            "type": "string",
+            "enum": [
+              "none",
+              "ngrok",
+              "tailscale-serve",
+              "tailscale-funnel"
+            ]
+          },
+          "ngrokAuthToken": {
+            "type": "string"
+          },
+          "ngrokDomain": {
+            "type": "string"
+          },
+          "allowNgrokFreeTier": {
+            "type": "boolean"
+          }
+        }
+      },
+      "streaming": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": {
+            "type": "boolean"
+          },
+          "sttProvider": {
+            "type": "string",
+            "enum": [
+              "openai-realtime"
+            ]
+          },
+          "openaiApiKey": {
+            "type": "string"
+          },
+          "sttModel": {
+            "type": "string"
+          },
+          "silenceDurationMs": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "vadThreshold": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1
+          },
+          "streamPath": {
+            "type": "string"
+          }
+        }
+      },
+      "publicUrl": {
+        "type": "string"
+      },
+      "skipSignatureVerification": {
+        "type": "boolean"
+      },
+      "stt": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "provider": {
+            "type": "string",
+            "enum": [
+              "openai"
+            ]
+          },
+          "model": {
+            "type": "string"
+          }
+        }
+      },
+      "tts": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "provider": {
+            "type": "string",
+            "enum": [
+              "openai"
+            ]
+          },
+          "model": {
+            "type": "string"
+          },
+          "voice": {
+            "type": "string"
+          },
+          "instructions": {
+            "type": "string"
+          }
+        }
+      },
+      "store": {
+        "type": "string"
+      },
+      "responseModel": {
+        "type": "string"
+      },
+      "responseSystemPrompt": {
+        "type": "string"
+      },
+      "responseTimeoutMs": {
+        "type": "integer",
+        "minimum": 1
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdbot/voice-call",
-  "version": "2026.1.16",
+  "version": "2026.1.20",
   "type": "module",
   "description": "Clawdbot voice-call plugin",
   "dependencies": {

package/src/config.ts

@@ -35,30 +35,36 @@ export type InboundPolicy = z.infer<typeof InboundPolicySchema>;
 // Provider-Specific Configuration
 // -----------------------------------------------------------------------------
 
-export const TelnyxConfigSchema = z.object({
+export const TelnyxConfigSchema = z
+  .object({
   /** Telnyx API v2 key */
   apiKey: z.string().min(1).optional(),
   /** Telnyx connection ID (from Call Control app) */
   connectionId: z.string().min(1).optional(),
   /** Public key for webhook signature verification */
   publicKey: z.string().min(1).optional(),
-});
+})
+  .strict();
 export type TelnyxConfig = z.infer<typeof TelnyxConfigSchema>;
 
-export const TwilioConfigSchema = z.object({
+export const TwilioConfigSchema = z
+  .object({
   /** Twilio Account SID */
   accountSid: z.string().min(1).optional(),
   /** Twilio Auth Token */
   authToken: z.string().min(1).optional(),
-});
+})
+  .strict();
 export type TwilioConfig = z.infer<typeof TwilioConfigSchema>;
 
-export const PlivoConfigSchema = z.object({
+export const PlivoConfigSchema = z
+  .object({
   /** Plivo Auth ID (starts with MA/SA) */
   authId: z.string().min(1).optional(),
   /** Plivo Auth Token */
   authToken: z.string().min(1).optional(),
-});
+})
+  .strict();
 export type PlivoConfig = z.infer<typeof PlivoConfigSchema>;
 
 // -----------------------------------------------------------------------------
@@ -72,6 +78,7 @@ export const SttConfigSchema = z
     /** Whisper model to use */
     model: z.string().min(1).default("whisper-1"),
   })
+  .strict()
   .default({ provider: "openai", model: "whisper-1" });
 export type SttConfig = z.infer<typeof SttConfigSchema>;
 
@@ -97,6 +104,7 @@ export const TtsConfigSchema = z
      */
     instructions: z.string().optional(),
   })
+  .strict()
   .default({ provider: "openai", model: "gpt-4o-mini-tts", voice: "coral" });
 export type TtsConfig = z.infer<typeof TtsConfigSchema>;
 
@@ -113,6 +121,7 @@ export const VoiceCallServeConfigSchema = z
     /** Webhook path */
     path: z.string().min(1).default("/voice/webhook"),
   })
+  .strict()
   .default({ port: 3334, bind: "127.0.0.1", path: "/voice/webhook" });
 export type VoiceCallServeConfig = z.infer<typeof VoiceCallServeConfigSchema>;
 
@@ -128,6 +137,7 @@ export const VoiceCallTailscaleConfigSchema = z
     /** Path for Tailscale serve/funnel (should usually match serve.path) */
     path: z.string().min(1).default("/voice/webhook"),
   })
+  .strict()
   .default({ mode: "off", path: "/voice/webhook" });
 export type VoiceCallTailscaleConfig = z.infer<
   typeof VoiceCallTailscaleConfigSchema
@@ -161,6 +171,7 @@ export const VoiceCallTunnelConfigSchema = z
      */
     allowNgrokFreeTier: z.boolean().default(true),
   })
+  .strict()
   .default({ provider: "none", allowNgrokFreeTier: true });
 export type VoiceCallTunnelConfig = z.infer<typeof VoiceCallTunnelConfigSchema>;
 
@@ -183,6 +194,7 @@ export const OutboundConfigSchema = z
     /** Seconds to wait after TTS before auto-hangup in notify mode */
     notifyHangupDelaySec: z.number().int().nonnegative().default(3),
   })
+  .strict()
   .default({ defaultMode: "notify", notifyHangupDelaySec: 3 });
 export type OutboundConfig = z.infer<typeof OutboundConfigSchema>;
 
@@ -207,6 +219,7 @@ export const VoiceCallStreamingConfigSchema = z
     /** WebSocket path for media stream connections */
     streamPath: z.string().min(1).default("/voice/stream"),
   })
+  .strict()
   .default({
     enabled: false,
     sttProvider: "openai-realtime",
@@ -223,7 +236,8 @@ export type VoiceCallStreamingConfig = z.infer<
 // Main Voice Call Configuration
 // -----------------------------------------------------------------------------
 
-export const VoiceCallConfigSchema = z.object({
+export const VoiceCallConfigSchema = z
+  .object({
   /** Enable voice call functionality */
   enabled: z.boolean().default(false),
 
@@ -307,7 +321,8 @@ export const VoiceCallConfigSchema = z.object({
 
   /** Timeout for response generation in ms (default 30s) */
   responseTimeoutMs: z.number().int().positive().default(30000),
-});
+})
+  .strict();
 
 export type VoiceCallConfig = z.infer<typeof VoiceCallConfigSchema>;
 

package/src/providers/twilio/api.ts

@@ -3,16 +3,33 @@ export async function twilioApiRequest<T = unknown>(params: {
   accountSid: string;
   authToken: string;
   endpoint: string;
-  body: Record<string, string>;
+  body: URLSearchParams | Record<string, string | string[]>;
   allowNotFound?: boolean;
 }): Promise<T> {
+  const bodyParams =
+    params.body instanceof URLSearchParams
+      ? params.body
+      : Object.entries(params.body).reduce<URLSearchParams>(
+          (acc, [key, value]) => {
+            if (Array.isArray(value)) {
+              for (const entry of value) {
+                acc.append(key, entry);
+              }
+            } else if (typeof value === "string") {
+              acc.append(key, value);
+            }
+            return acc;
+          },
+          new URLSearchParams(),
+        );
+
   const response = await fetch(`${params.baseUrl}${params.endpoint}`, {
     method: "POST",
     headers: {
       Authorization: `Basic ${Buffer.from(`${params.accountSid}:${params.authToken}`).toString("base64")}`,
       "Content-Type": "application/x-www-form-urlencoded",
     },
-    body: new URLSearchParams(params.body),
+    body: bodyParams,
   });
 
   if (!response.ok) {
@@ -26,4 +43,3 @@ export async function twilioApiRequest<T = unknown>(params: {
   const text = await response.text();
   return text ? (JSON.parse(text) as T) : (undefined as T);
 }
-

package/src/providers/twilio.ts

@@ -62,6 +62,37 @@ export class TwilioProvider implements VoiceCallProvider {
   /** Map of call SID to stream SID for media streams */
   private callStreamMap = new Map<string, string>();
 
+  /** Storage for TwiML content (for notify mode with URL-based TwiML) */
+  private readonly twimlStorage = new Map<string, string>();
+  /** Track notify-mode calls to avoid streaming on follow-up callbacks */
+  private readonly notifyCalls = new Set<string>();
+
+  /**
+   * Delete stored TwiML for a given `callId`.
+   *
+   * We keep TwiML in-memory only long enough to satisfy the initial Twilio
+   * webhook request (notify mode). Subsequent webhooks should not reuse it.
+   */
+  private deleteStoredTwiml(callId: string): void {
+    this.twimlStorage.delete(callId);
+    this.notifyCalls.delete(callId);
+  }
+
+  /**
+   * Delete stored TwiML for a call, addressed by Twilio's provider call SID.
+   *
+   * This is used when we only have `providerCallId` (e.g. hangup).
+   */
+  private deleteStoredTwimlForProviderCall(providerCallId: string): void {
+    const webhookUrl = this.callWebhookUrls.get(providerCallId);
+    if (!webhookUrl) return;
+
+    const callIdMatch = webhookUrl.match(/callId=([^&]+)/);
+    if (!callIdMatch) return;
+
+    this.deleteStoredTwiml(callIdMatch[1]);
+  }
+
   constructor(config: TwilioConfig, options: TwilioProviderOptions = {}) {
     if (!config.accountSid) {
       throw new Error("Twilio Account SID is required");
@@ -109,7 +140,7 @@ export class TwilioProvider implements VoiceCallProvider {
    */
   private async apiRequest<T = unknown>(
     endpoint: string,
-    params: Record<string, string>,
+    params: Record<string, string | string[]>,
     options?: { allowNotFound?: boolean },
   ): Promise<T> {
     return await twilioApiRequest<T>({
@@ -228,8 +259,14 @@ export class TwilioProvider implements VoiceCallProvider {
       case "busy":
       case "no-answer":
       case "failed":
+        if (callIdOverride) {
+          this.deleteStoredTwiml(callIdOverride);
+        }
         return { ...baseEvent, type: "call.ended", reason: callStatus };
       case "canceled":
+        if (callIdOverride) {
+          this.deleteStoredTwiml(callIdOverride);
+        }
         return { ...baseEvent, type: "call.ended", reason: "hangup-bot" };
       default:
         return null;
@@ -252,13 +289,38 @@ export class TwilioProvider implements VoiceCallProvider {
     if (!ctx) return TwilioProvider.EMPTY_TWIML;
 
     const params = new URLSearchParams(ctx.rawBody);
+    const type =
+      typeof ctx.query?.type === "string" ? ctx.query.type.trim() : undefined;
+    const isStatusCallback = type === "status";
     const callStatus = params.get("CallStatus");
     const direction = params.get("Direction");
+    const callIdFromQuery =
+      typeof ctx.query?.callId === "string" && ctx.query.callId.trim()
+        ? ctx.query.callId.trim()
+        : undefined;
+
+    // Avoid logging webhook params/TwiML (may contain PII).
+
+    // Handle initial TwiML request (when Twilio first initiates the call)
+    // Check if we have stored TwiML for this call (notify mode)
+    if (callIdFromQuery && !isStatusCallback) {
+      const storedTwiml = this.twimlStorage.get(callIdFromQuery);
+      if (storedTwiml) {
+        // Clean up after serving (one-time use)
+        this.deleteStoredTwiml(callIdFromQuery);
+        return storedTwiml;
+      }
+      if (this.notifyCalls.has(callIdFromQuery)) {
+        return TwilioProvider.EMPTY_TWIML;
+      }
+    }
 
-    console.log(
-      `[voice-call] generateTwimlResponse: status=${callStatus} direction=${direction}`,
-    );
+    // Status callbacks should not receive TwiML.
+    if (isStatusCallback) {
+      return TwilioProvider.EMPTY_TWIML;
+    }
 
+    // Handle subsequent webhook requests (status callbacks, etc.)
     // For inbound calls, answer immediately with stream
     if (direction === "inbound") {
       const streamUrl = this.getStreamUrl();
@@ -328,22 +390,29 @@ export class TwilioProvider implements VoiceCallProvider {
     const url = new URL(input.webhookUrl);
     url.searchParams.set("callId", input.callId);
 
-    // Build request params
-    const params: Record<string, string> = {
+    // Create separate URL for status callbacks (required by Twilio)
+    const statusUrl = new URL(input.webhookUrl);
+    statusUrl.searchParams.set("callId", input.callId);
+    statusUrl.searchParams.set("type", "status"); // Differentiate from TwiML requests
+
+    // Store TwiML content if provided (for notify mode)
+    // We now serve it from the webhook endpoint instead of sending inline
+    if (input.inlineTwiml) {
+      this.twimlStorage.set(input.callId, input.inlineTwiml);
+      this.notifyCalls.add(input.callId);
+    }
+
+    // Build request params - always use URL-based TwiML.
+    // Twilio silently ignores `StatusCallback` when using the inline `Twiml` parameter.
+    const params: Record<string, string | string[]> = {
       To: input.to,
       From: input.from,
-      StatusCallback: url.toString(),
-      StatusCallbackEvent: "initiated ringing answered completed",
+      Url: url.toString(), // TwiML serving endpoint
+      StatusCallback: statusUrl.toString(), // Separate status callback endpoint
+      StatusCallbackEvent: ["initiated", "ringing", "answered", "completed"],
       Timeout: "30",
     };
 
-    // Use inline TwiML for notify mode (simpler, no webhook needed)
-    if (input.inlineTwiml) {
-      params.Twiml = input.inlineTwiml;
-    } else {
-      params.Url = url.toString();
-    }
-
     const result = await this.apiRequest<TwilioCallResponse>(
       "/Calls.json",
       params,
@@ -361,6 +430,8 @@ export class TwilioProvider implements VoiceCallProvider {
    * Hang up a call via Twilio API.
    */
   async hangupCall(input: HangupCallInput): Promise<void> {
+    this.deleteStoredTwimlForProviderCall(input.providerCallId);
+
     this.callWebhookUrls.delete(input.providerCallId);
 
     await this.apiRequest(

package/src/tunnel.ts

@@ -230,12 +230,13 @@ export async function startTailscaleTunnel(config: {
     throw new Error("Could not get Tailscale DNS name. Is Tailscale running?");
   }
 
-  const localUrl = `http://127.0.0.1:${config.port}`;
+  const path = config.path.startsWith("/") ? config.path : `/${config.path}`;
+  const localUrl = `http://127.0.0.1:${config.port}${path}`;
 
   return new Promise((resolve, reject) => {
     const proc = spawn(
       "tailscale",
-      [config.mode, "--bg", "--yes", "--set-path", config.path, localUrl],
+      [config.mode, "--bg", "--yes", "--set-path", path, localUrl],
       { stdio: ["ignore", "pipe", "pipe"] },
     );
 
@@ -247,7 +248,7 @@ export async function startTailscaleTunnel(config: {
     proc.on("close", (code) => {
       clearTimeout(timeout);
       if (code === 0) {
-        const publicUrl = `https://${dnsName}${config.path}`;
+        const publicUrl = `https://${dnsName}${path}`;
         console.log(
           `[voice-call] Tailscale ${config.mode} active: ${publicUrl}`,
         );
@@ -256,7 +257,7 @@ export async function startTailscaleTunnel(config: {
           publicUrl,
           provider: `tailscale-${config.mode}`,
           stop: async () => {
-            await stopTailscaleTunnel(config.mode, config.path);
+            await stopTailscaleTunnel(config.mode, path);
           },
         });
       } else {

package/src/webhook-security.test.ts

@@ -2,7 +2,7 @@ import crypto from "node:crypto";
 
 import { describe, expect, it } from "vitest";
 
-import { verifyPlivoWebhook } from "./webhook-security.js";
+import { verifyPlivoWebhook, verifyTwilioWebhook } from "./webhook-security.js";
 
 function canonicalizeBase64(input: string): string {
   return Buffer.from(input, "base64").toString("base64");
@@ -71,6 +71,26 @@ function plivoV3Signature(params: {
   return canonicalizeBase64(digest);
 }
 
+function twilioSignature(params: {
+  authToken: string;
+  url: string;
+  postBody: string;
+}): string {
+  let dataToSign = params.url;
+  const sortedParams = Array.from(
+    new URLSearchParams(params.postBody).entries(),
+  ).sort((a, b) => a[0].localeCompare(b[0]));
+
+  for (const [key, value] of sortedParams) {
+    dataToSign += key + value;
+  }
+
+  return crypto
+    .createHmac("sha1", params.authToken)
+    .update(dataToSign)
+    .digest("base64");
+}
+
 describe("verifyPlivoWebhook", () => {
   it("accepts valid V2 signature", () => {
     const authToken = "test-auth-token";
@@ -154,3 +174,35 @@ describe("verifyPlivoWebhook", () => {
   });
 });
 
+describe("verifyTwilioWebhook", () => {
+  it("uses request query when publicUrl omits it", () => {
+    const authToken = "test-auth-token";
+    const publicUrl = "https://example.com/voice/webhook";
+    const urlWithQuery = `${publicUrl}?callId=abc`;
+    const postBody = "CallSid=CS123&CallStatus=completed&From=%2B15550000000";
+
+    const signature = twilioSignature({
+      authToken,
+      url: urlWithQuery,
+      postBody,
+    });
+
+    const result = verifyTwilioWebhook(
+      {
+        headers: {
+          host: "example.com",
+          "x-forwarded-proto": "https",
+          "x-twilio-signature": signature,
+        },
+        rawBody: postBody,
+        url: "http://local/voice/webhook?callId=abc",
+        method: "POST",
+        query: { callId: "abc" },
+      },
+      authToken,
+      { publicUrl },
+    );
+
+    expect(result.ok).toBe(true);
+  });
+});

package/src/webhook-security.ts

@@ -25,7 +25,7 @@ export function validateTwilioSignature(
 
   // Sort params alphabetically and append key+value
   const sortedParams = Array.from(params.entries()).sort((a, b) =>
-    a[0].localeCompare(b[0]),
+    a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0,
   );
 
   for (const [key, value] of sortedParams) {
@@ -98,6 +98,25 @@ export function reconstructWebhookUrl(ctx: WebhookContext): string {
   return `${proto}://${host}${path}`;
 }
 
+function buildTwilioVerificationUrl(
+  ctx: WebhookContext,
+  publicUrl?: string,
+): string {
+  if (!publicUrl) {
+    return reconstructWebhookUrl(ctx);
+  }
+
+  try {
+    const base = new URL(publicUrl);
+    const requestUrl = new URL(ctx.url);
+    base.pathname = requestUrl.pathname;
+    base.search = requestUrl.search;
+    return base.toString();
+  } catch {
+    return publicUrl;
+  }
+}
+
 /**
  * Get a header value, handling both string and string[] types.
  */
@@ -154,7 +173,7 @@ export function verifyTwilioWebhook(
   }
 
   // Reconstruct the URL Twilio used
-  const verificationUrl = options?.publicUrl || reconstructWebhookUrl(ctx);
+  const verificationUrl = buildTwilioVerificationUrl(ctx, options?.publicUrl);
 
   // Parse the body as URL-encoded params
   const params = new URLSearchParams(ctx.rawBody);