@openclaw/voice-call 2026.2.25 → 2026.3.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 2026.3.1
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.2.26
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
 ## 2026.2.25
 
 ### Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/voice-call",
-  "version": "2026.2.25",
+  "version": "2026.3.1",
   "description": "OpenClaw voice-call plugin",
   "type": "module",
   "dependencies": {

package/src/http-headers.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { getHeader } from "./http-headers.js";
+
+describe("getHeader", () => {
+  it("returns first value when header is an array", () => {
+    expect(getHeader({ "x-test": ["first", "second"] }, "x-test")).toBe("first");
+  });
+
+  it("matches headers case-insensitively", () => {
+    expect(getHeader({ "X-Twilio-Signature": "sig-1" }, "x-twilio-signature")).toBe("sig-1");
+  });
+
+  it("returns undefined for missing header", () => {
+    expect(getHeader({ host: "example.com" }, "x-missing")).toBeUndefined();
+  });
+});

package/src/http-headers.ts

@@ -0,0 +1,12 @@
+export type HttpHeaderMap = Record<string, string | string[] | undefined>;
+
+export function getHeader(headers: HttpHeaderMap, name: string): string | undefined {
+  const target = name.toLowerCase();
+  const direct = headers[target];
+  const value =
+    direct ?? Object.entries(headers).find(([key]) => key.toLowerCase() === target)?.[1];
+  if (Array.isArray(value)) {
+    return value[0];
+  }
+  return value;
+}

package/src/providers/base.ts

@@ -4,6 +4,7 @@ import type {
   InitiateCallResult,
   PlayTtsInput,
   ProviderName,
+  WebhookParseOptions,
   ProviderWebhookParseResult,
   StartListeningInput,
   StopListeningInput,
@@ -36,7 +37,7 @@ export interface VoiceCallProvider {
    * Parse provider-specific webhook payload into normalized events.
    * Returns events and optional response to send back to provider.
    */
-  parseWebhookEvent(ctx: WebhookContext): ProviderWebhookParseResult;
+  parseWebhookEvent(ctx: WebhookContext, options?: WebhookParseOptions): ProviderWebhookParseResult;
 
   /**
    * Initiate an outbound call.

package/src/providers/mock.ts

@@ -6,6 +6,7 @@ import type {
   InitiateCallResult,
   NormalizedEvent,
   PlayTtsInput,
+  WebhookParseOptions,
   ProviderWebhookParseResult,
   StartListeningInput,
   StopListeningInput,
@@ -28,7 +29,10 @@ export class MockProvider implements VoiceCallProvider {
     return { ok: true };
   }
 
-  parseWebhookEvent(ctx: WebhookContext): ProviderWebhookParseResult {
+  parseWebhookEvent(
+    ctx: WebhookContext,
+    _options?: WebhookParseOptions,
+  ): ProviderWebhookParseResult {
     try {
       const payload = JSON.parse(ctx.rawBody);
       const events: NormalizedEvent[] = [];

package/src/providers/plivo.test.ts

@@ -24,4 +24,26 @@ describe("PlivoProvider", () => {
     expect(result.providerResponseBody).toContain("<Wait");
     expect(result.providerResponseBody).toContain('length="300"');
   });
+
+  it("uses verified request key when provided", () => {
+    const provider = new PlivoProvider({
+      authId: "MA000000000000000000",
+      authToken: "test-token",
+    });
+
+    const result = provider.parseWebhookEvent(
+      {
+        headers: { host: "example.com", "x-plivo-signature-v3-nonce": "nonce-1" },
+        rawBody:
+          "CallUUID=call-uuid&CallStatus=in-progress&Direction=outbound&From=%2B15550000000&To=%2B15550000001&Event=StartApp",
+        url: "https://example.com/voice/webhook?provider=plivo&flow=answer&callId=internal-call-id",
+        method: "POST",
+        query: { provider: "plivo", flow: "answer", callId: "internal-call-id" },
+      },
+      { verifiedRequestKey: "plivo:v3:verified" },
+    );
+
+    expect(result.events).toHaveLength(1);
+    expect(result.events[0]?.dedupeKey).toBe("plivo:v3:verified");
+  });
 });

package/src/providers/plivo.ts

@@ -1,5 +1,6 @@
 import crypto from "node:crypto";
 import type { PlivoConfig, WebhookSecurityConfig } from "../config.js";
+import { getHeader } from "../http-headers.js";
 import type {
   HangupCallInput,
   InitiateCallInput,
@@ -10,11 +11,13 @@ import type {
   StartListeningInput,
   StopListeningInput,
   WebhookContext,
+  WebhookParseOptions,
   WebhookVerificationResult,
 } from "../types.js";
 import { escapeXml } from "../voice-mapping.js";
 import { reconstructWebhookUrl, verifyPlivoWebhook } from "../webhook-security.js";
 import type { VoiceCallProvider } from "./base.js";
+import { guardedJsonApiRequest } from "./shared/guarded-json-api.js";
 
 export interface PlivoProviderOptions {
   /** Override public URL origin for signature verification */
@@ -30,17 +33,6 @@ export interface PlivoProviderOptions {
 type PendingSpeak = { text: string; locale?: string };
 type PendingListen = { language?: string };
 
-function getHeader(
-  headers: Record<string, string | string[] | undefined>,
-  name: string,
-): string | undefined {
-  const value = headers[name.toLowerCase()];
-  if (Array.isArray(value)) {
-    return value[0];
-  }
-  return value;
-}
-
 function createPlivoRequestDedupeKey(ctx: WebhookContext): string {
   const nonceV3 = getHeader(ctx.headers, "x-plivo-signature-v3-nonce");
   if (nonceV3) {
@@ -60,6 +52,7 @@ export class PlivoProvider implements VoiceCallProvider {
   private readonly authToken: string;
   private readonly baseUrl: string;
   private readonly options: PlivoProviderOptions;
+  private readonly apiHost: string;
 
   // Best-effort mapping between create-call request UUID and call UUID.
   private requestUuidToCallUuid = new Map<string, string>();
@@ -82,6 +75,7 @@ export class PlivoProvider implements VoiceCallProvider {
     this.authId = config.authId;
     this.authToken = config.authToken;
     this.baseUrl = `https://api.plivo.com/v1/Account/${this.authId}`;
+    this.apiHost = new URL(this.baseUrl).hostname;
     this.options = options;
   }
 
@@ -92,25 +86,19 @@ export class PlivoProvider implements VoiceCallProvider {
     allowNotFound?: boolean;
   }): Promise<T> {
     const { method, endpoint, body, allowNotFound } = params;
-    const response = await fetch(`${this.baseUrl}${endpoint}`, {
+    return await guardedJsonApiRequest<T>({
+      url: `${this.baseUrl}${endpoint}`,
       method,
       headers: {
         Authorization: `Basic ${Buffer.from(`${this.authId}:${this.authToken}`).toString("base64")}`,
         "Content-Type": "application/json",
       },
-      body: body ? JSON.stringify(body) : undefined,
+      body,
+      allowNotFound,
+      allowedHostnames: [this.apiHost],
+      auditContext: "voice-call.plivo.api",
+      errorPrefix: "Plivo API error",
     });
-
-    if (!response.ok) {
-      if (allowNotFound && response.status === 404) {
-        return undefined as T;
-      }
-      const errorText = await response.text();
-      throw new Error(`Plivo API error: ${response.status} ${errorText}`);
-    }
-
-    const text = await response.text();
-    return text ? (JSON.parse(text) as T) : (undefined as T);
   }
 
   verifyWebhook(ctx: WebhookContext): WebhookVerificationResult {
@@ -127,10 +115,18 @@ export class PlivoProvider implements VoiceCallProvider {
       console.warn(`[plivo] Webhook verification failed: ${result.reason}`);
     }
 
-    return { ok: result.ok, reason: result.reason, isReplay: result.isReplay };
+    return {
+      ok: result.ok,
+      reason: result.reason,
+      isReplay: result.isReplay,
+      verifiedRequestKey: result.verifiedRequestKey,
+    };
   }
 
-  parseWebhookEvent(ctx: WebhookContext): ProviderWebhookParseResult {
+  parseWebhookEvent(
+    ctx: WebhookContext,
+    options?: WebhookParseOptions,
+  ): ProviderWebhookParseResult {
     const flow = typeof ctx.query?.flow === "string" ? ctx.query.flow.trim() : "";
 
     const parsed = this.parseBody(ctx.rawBody);
@@ -196,7 +192,7 @@ export class PlivoProvider implements VoiceCallProvider {
 
     // Normal events.
     const callIdFromQuery = this.getCallIdFromQuery(ctx);
-    const dedupeKey = createPlivoRequestDedupeKey(ctx);
+    const dedupeKey = options?.verifiedRequestKey ?? createPlivoRequestDedupeKey(ctx);
     const event = this.normalizeEvent(parsed, callIdFromQuery, dedupeKey);
 
     return {

package/src/providers/shared/guarded-json-api.ts

@@ -0,0 +1,42 @@
+import { fetchWithSsrFGuard } from "openclaw/plugin-sdk";
+
+type GuardedJsonApiRequestParams = {
+  url: string;
+  method: "GET" | "POST" | "DELETE" | "PUT" | "PATCH";
+  headers: Record<string, string>;
+  body?: Record<string, unknown>;
+  allowNotFound?: boolean;
+  allowedHostnames: string[];
+  auditContext: string;
+  errorPrefix: string;
+};
+
+export async function guardedJsonApiRequest<T = unknown>(
+  params: GuardedJsonApiRequestParams,
+): Promise<T> {
+  const { response, release } = await fetchWithSsrFGuard({
+    url: params.url,
+    init: {
+      method: params.method,
+      headers: params.headers,
+      body: params.body ? JSON.stringify(params.body) : undefined,
+    },
+    policy: { allowedHostnames: params.allowedHostnames },
+    auditContext: params.auditContext,
+  });
+
+  try {
+    if (!response.ok) {
+      if (params.allowNotFound && response.status === 404) {
+        return undefined as T;
+      }
+      const errorText = await response.text();
+      throw new Error(`${params.errorPrefix}: ${response.status} ${errorText}`);
+    }
+
+    const text = await response.text();
+    return text ? (JSON.parse(text) as T) : (undefined as T);
+  } finally {
+    await release();
+  }
+}

package/src/providers/telnyx.test.ts

@@ -133,7 +133,34 @@ describe("TelnyxProvider.verifyWebhook", () => {
 
     expect(first.ok).toBe(true);
     expect(first.isReplay).toBeFalsy();
+    expect(first.verifiedRequestKey).toBeTruthy();
     expect(second.ok).toBe(true);
     expect(second.isReplay).toBe(true);
+    expect(second.verifiedRequestKey).toBe(first.verifiedRequestKey);
+  });
+});
+
+describe("TelnyxProvider.parseWebhookEvent", () => {
+  it("uses verified request key for manager dedupe", () => {
+    const provider = new TelnyxProvider({
+      apiKey: "KEY123",
+      connectionId: "CONN456",
+      publicKey: undefined,
+    });
+    const result = provider.parseWebhookEvent(
+      createCtx({
+        rawBody: JSON.stringify({
+          data: {
+            id: "evt-123",
+            event_type: "call.initiated",
+            payload: { call_control_id: "call-1" },
+          },
+        }),
+      }),
+      { verifiedRequestKey: "telnyx:req:abc" },
+    );
+
+    expect(result.events).toHaveLength(1);
+    expect(result.events[0]?.dedupeKey).toBe("telnyx:req:abc");
   });
 });

package/src/providers/telnyx.ts

@@ -11,10 +11,12 @@ import type {
   StartListeningInput,
   StopListeningInput,
   WebhookContext,
+  WebhookParseOptions,
   WebhookVerificationResult,
 } from "../types.js";
 import { verifyTelnyxWebhook } from "../webhook-security.js";
 import type { VoiceCallProvider } from "./base.js";
+import { guardedJsonApiRequest } from "./shared/guarded-json-api.js";
 
 /**
  * Telnyx Voice API provider implementation.
@@ -35,6 +37,7 @@ export class TelnyxProvider implements VoiceCallProvider {
   private readonly publicKey: string | undefined;
   private readonly options: TelnyxProviderOptions;
   private readonly baseUrl = "https://api.telnyx.com/v2";
+  private readonly apiHost = "api.telnyx.com";
 
   constructor(config: TelnyxConfig, options: TelnyxProviderOptions = {}) {
     if (!config.apiKey) {
@@ -58,25 +61,19 @@ export class TelnyxProvider implements VoiceCallProvider {
     body: Record<string, unknown>,
     options?: { allowNotFound?: boolean },
   ): Promise<T> {
-    const response = await fetch(`${this.baseUrl}${endpoint}`, {
+    return await guardedJsonApiRequest<T>({
+      url: `${this.baseUrl}${endpoint}`,
       method: "POST",
       headers: {
         Authorization: `Bearer ${this.apiKey}`,
         "Content-Type": "application/json",
       },
-      body: JSON.stringify(body),
+      body,
+      allowNotFound: options?.allowNotFound,
+      allowedHostnames: [this.apiHost],
+      auditContext: "voice-call.telnyx.api",
+      errorPrefix: "Telnyx API error",
     });
-
-    if (!response.ok) {
-      if (options?.allowNotFound && response.status === 404) {
-        return undefined as T;
-      }
-      const errorText = await response.text();
-      throw new Error(`Telnyx API error: ${response.status} ${errorText}`);
-    }
-
-    const text = await response.text();
-    return text ? (JSON.parse(text) as T) : (undefined as T);
   }
 
   /**
@@ -87,13 +84,21 @@ export class TelnyxProvider implements VoiceCallProvider {
       skipVerification: this.options.skipVerification,
     });
 
-    return { ok: result.ok, reason: result.reason, isReplay: result.isReplay };
+    return {
+      ok: result.ok,
+      reason: result.reason,
+      isReplay: result.isReplay,
+      verifiedRequestKey: result.verifiedRequestKey,
+    };
   }
 
   /**
    * Parse Telnyx webhook event into normalized format.
    */
-  parseWebhookEvent(ctx: WebhookContext): ProviderWebhookParseResult {
+  parseWebhookEvent(
+    ctx: WebhookContext,
+    options?: WebhookParseOptions,
+  ): ProviderWebhookParseResult {
     try {
       const payload = JSON.parse(ctx.rawBody);
       const data = payload.data;
@@ -102,7 +107,7 @@ export class TelnyxProvider implements VoiceCallProvider {
         return { events: [], statusCode: 200 };
       }
 
-      const event = this.normalizeEvent(data);
+      const event = this.normalizeEvent(data, options?.verifiedRequestKey);
       return {
         events: event ? [event] : [],
         statusCode: 200,
@@ -115,7 +120,7 @@ export class TelnyxProvider implements VoiceCallProvider {
   /**
    * Convert Telnyx event to normalized event format.
    */
-  private normalizeEvent(data: TelnyxEvent): NormalizedEvent | null {
+  private normalizeEvent(data: TelnyxEvent, dedupeKey?: string): NormalizedEvent | null {
     // Decode client_state from Base64 (we encode it in initiateCall)
     let callId = "";
     if (data.payload?.client_state) {
@@ -132,6 +137,7 @@ export class TelnyxProvider implements VoiceCallProvider {
 
     const baseEvent = {
       id: data.id || crypto.randomUUID(),
+      dedupeKey,
       callId,
       providerCallId: data.payload?.call_control_id,
       timestamp: Date.now(),

package/src/providers/twilio/webhook.ts

@@ -29,5 +29,6 @@ export function verifyTwilioProviderWebhook(params: {
     ok: result.ok,
     reason: result.reason,
     isReplay: result.isReplay,
+    verifiedRequestKey: result.verifiedRequestKey,
   };
 }

package/src/providers/twilio.test.ts

@@ -60,7 +60,7 @@ describe("TwilioProvider", () => {
     expect(result.providerResponseBody).toContain("<Connect>");
   });
 
-  it("uses a stable dedupeKey for identical request payloads", () => {
+  it("uses a stable fallback dedupeKey for identical request payloads", () => {
     const provider = createProvider();
     const rawBody = "CallSid=CA789&Direction=inbound&SpeechResult=hello";
     const ctxA = {
@@ -78,10 +78,31 @@ describe("TwilioProvider", () => {
     expect(eventA).toBeDefined();
     expect(eventB).toBeDefined();
     expect(eventA?.id).not.toBe(eventB?.id);
-    expect(eventA?.dedupeKey).toBe("twilio:idempotency:idem-123");
+    expect(eventA?.dedupeKey).toContain("twilio:fallback:");
     expect(eventA?.dedupeKey).toBe(eventB?.dedupeKey);
   });
 
+  it("uses verified request key for dedupe and ignores idempotency header changes", () => {
+    const provider = createProvider();
+    const rawBody = "CallSid=CA790&Direction=inbound&SpeechResult=hello";
+    const ctxA = {
+      ...createContext(rawBody, { callId: "call-1", turnToken: "turn-1" }),
+      headers: { "i-twilio-idempotency-token": "idem-a" },
+    };
+    const ctxB = {
+      ...createContext(rawBody, { callId: "call-1", turnToken: "turn-1" }),
+      headers: { "i-twilio-idempotency-token": "idem-b" },
+    };
+
+    const eventA = provider.parseWebhookEvent(ctxA, { verifiedRequestKey: "twilio:req:abc" })
+      .events[0];
+    const eventB = provider.parseWebhookEvent(ctxB, { verifiedRequestKey: "twilio:req:abc" })
+      .events[0];
+
+    expect(eventA?.dedupeKey).toBe("twilio:req:abc");
+    expect(eventB?.dedupeKey).toBe("twilio:req:abc");
+  });
+
   it("keeps turnToken from query on speech events", () => {
     const provider = createProvider();
     const ctx = createContext("CallSid=CA222&Direction=inbound&SpeechResult=hello", {

package/src/providers/twilio.ts

@@ -1,5 +1,6 @@
 import crypto from "node:crypto";
 import type { TwilioConfig, WebhookSecurityConfig } from "../config.js";
+import { getHeader } from "../http-headers.js";
 import type { MediaStreamHandler } from "../media-stream.js";
 import { chunkAudio } from "../telephony-audio.js";
 import type { TelephonyTtsProvider } from "../telephony-tts.js";
@@ -13,6 +14,7 @@ import type {
   StartListeningInput,
   StopListeningInput,
   WebhookContext,
+  WebhookParseOptions,
   WebhookVerificationResult,
 } from "../types.js";
 import { escapeXml, mapVoiceToPolly } from "../voice-mapping.js";
@@ -20,30 +22,24 @@ import type { VoiceCallProvider } from "./base.js";
 import { twilioApiRequest } from "./twilio/api.js";
 import { verifyTwilioProviderWebhook } from "./twilio/webhook.js";
 
-function getHeader(
-  headers: Record<string, string | string[] | undefined>,
-  name: string,
-): string | undefined {
-  const value = headers[name.toLowerCase()];
-  if (Array.isArray(value)) {
-    return value[0];
-  }
-  return value;
-}
-
-function createTwilioRequestDedupeKey(ctx: WebhookContext): string {
-  const idempotencyToken = getHeader(ctx.headers, "i-twilio-idempotency-token");
-  if (idempotencyToken) {
-    return `twilio:idempotency:${idempotencyToken}`;
+function createTwilioRequestDedupeKey(ctx: WebhookContext, verifiedRequestKey?: string): string {
+  if (verifiedRequestKey) {
+    return verifiedRequestKey;
   }
 
   const signature = getHeader(ctx.headers, "x-twilio-signature") ?? "";
+  const params = new URLSearchParams(ctx.rawBody);
+  const callSid = params.get("CallSid") ?? "";
+  const callStatus = params.get("CallStatus") ?? "";
+  const direction = params.get("Direction") ?? "";
   const callId = typeof ctx.query?.callId === "string" ? ctx.query.callId.trim() : "";
   const flow = typeof ctx.query?.flow === "string" ? ctx.query.flow.trim() : "";
   const turnToken = typeof ctx.query?.turnToken === "string" ? ctx.query.turnToken.trim() : "";
   return `twilio:fallback:${crypto
     .createHash("sha256")
-    .update(`${signature}\n${callId}\n${flow}\n${turnToken}\n${ctx.rawBody}`)
+    .update(
+      `${signature}\n${callSid}\n${callStatus}\n${direction}\n${callId}\n${flow}\n${turnToken}\n${ctx.rawBody}`,
+    )
     .digest("hex")}`;
 }
 
@@ -232,7 +228,10 @@ export class TwilioProvider implements VoiceCallProvider {
   /**
    * Parse Twilio webhook event into normalized format.
    */
-  parseWebhookEvent(ctx: WebhookContext): ProviderWebhookParseResult {
+  parseWebhookEvent(
+    ctx: WebhookContext,
+    options?: WebhookParseOptions,
+  ): ProviderWebhookParseResult {
     try {
       const params = new URLSearchParams(ctx.rawBody);
       const callIdFromQuery =
@@ -243,7 +242,7 @@ export class TwilioProvider implements VoiceCallProvider {
         typeof ctx.query?.turnToken === "string" && ctx.query.turnToken.trim()
           ? ctx.query.turnToken.trim()
           : undefined;
-      const dedupeKey = createTwilioRequestDedupeKey(ctx);
+      const dedupeKey = createTwilioRequestDedupeKey(ctx, options?.verifiedRequestKey);
       const event = this.normalizeEvent(params, {
         callIdOverride: callIdFromQuery,
         dedupeKey,

package/src/types.ts

@@ -177,6 +177,13 @@ export type WebhookVerificationResult = {
   reason?: string;
   /** Signature is valid, but request was seen before within replay window. */
   isReplay?: boolean;
+  /** Stable key derived from authenticated request material. */
+  verifiedRequestKey?: string;
+};
+
+export type WebhookParseOptions = {
+  /** Stable request key from verifyWebhook. */
+  verifiedRequestKey?: string;
 };
 
 export type WebhookContext = {

package/src/webhook/stale-call-reaper.ts

@@ -0,0 +1,33 @@
+import type { CallManager } from "../manager.js";
+
+const CHECK_INTERVAL_MS = 30_000;
+
+export function startStaleCallReaper(params: {
+  manager: CallManager;
+  staleCallReaperSeconds?: number;
+}): (() => void) | null {
+  const maxAgeSeconds = params.staleCallReaperSeconds;
+  if (!maxAgeSeconds || maxAgeSeconds <= 0) {
+    return null;
+  }
+
+  const maxAgeMs = maxAgeSeconds * 1000;
+  const interval = setInterval(() => {
+    const now = Date.now();
+    for (const call of params.manager.getActiveCalls()) {
+      const age = now - call.startedAt;
+      if (age > maxAgeMs) {
+        console.log(
+          `[voice-call] Reaping stale call ${call.callId} (age: ${Math.round(age / 1000)}s, state: ${call.state})`,
+        );
+        void params.manager.endCall(call.callId).catch((err) => {
+          console.warn(`[voice-call] Reaper failed to end call ${call.callId}:`, err);
+        });
+      }
+    }
+  }, CHECK_INTERVAL_MS);
+
+  return () => {
+    clearInterval(interval);
+  };
+}

package/src/webhook-security.test.ts

@@ -198,8 +198,26 @@ describe("verifyPlivoWebhook", () => {
 
     expect(first.ok).toBe(true);
     expect(first.isReplay).toBeFalsy();
+    expect(first.verifiedRequestKey).toBeTruthy();
     expect(second.ok).toBe(true);
     expect(second.isReplay).toBe(true);
+    expect(second.verifiedRequestKey).toBe(first.verifiedRequestKey);
+  });
+
+  it("returns a stable request key when verification is skipped", () => {
+    const ctx = {
+      headers: {},
+      rawBody: "CallUUID=uuid&CallStatus=in-progress",
+      url: "https://example.com/voice/webhook",
+      method: "POST" as const,
+    };
+    const first = verifyPlivoWebhook(ctx, "token", { skipVerification: true });
+    const second = verifyPlivoWebhook(ctx, "token", { skipVerification: true });
+
+    expect(first.ok).toBe(true);
+    expect(first.verifiedRequestKey).toMatch(/^plivo:skip:/);
+    expect(second.verifiedRequestKey).toBe(first.verifiedRequestKey);
+    expect(second.isReplay).toBe(true);
   });
 });
 
@@ -229,8 +247,26 @@ describe("verifyTelnyxWebhook", () => {
 
     expect(first.ok).toBe(true);
     expect(first.isReplay).toBeFalsy();
+    expect(first.verifiedRequestKey).toBeTruthy();
     expect(second.ok).toBe(true);
     expect(second.isReplay).toBe(true);
+    expect(second.verifiedRequestKey).toBe(first.verifiedRequestKey);
+  });
+
+  it("returns a stable request key when verification is skipped", () => {
+    const ctx = {
+      headers: {},
+      rawBody: JSON.stringify({ data: { event_type: "call.initiated" } }),
+      url: "https://example.com/voice/webhook",
+      method: "POST" as const,
+    };
+    const first = verifyTelnyxWebhook(ctx, undefined, { skipVerification: true });
+    const second = verifyTelnyxWebhook(ctx, undefined, { skipVerification: true });
+
+    expect(first.ok).toBe(true);
+    expect(first.verifiedRequestKey).toMatch(/^telnyx:skip:/);
+    expect(second.verifiedRequestKey).toBe(first.verifiedRequestKey);
+    expect(second.isReplay).toBe(true);
   });
 });
 
@@ -304,8 +340,58 @@ describe("verifyTwilioWebhook", () => {
 
     expect(first.ok).toBe(true);
     expect(first.isReplay).toBeFalsy();
+    expect(first.verifiedRequestKey).toBeTruthy();
+    expect(second.ok).toBe(true);
+    expect(second.isReplay).toBe(true);
+    expect(second.verifiedRequestKey).toBe(first.verifiedRequestKey);
+  });
+
+  it("treats changed idempotency header as replay for identical signed requests", () => {
+    const authToken = "test-auth-token";
+    const publicUrl = "https://example.com/voice/webhook";
+    const urlWithQuery = `${publicUrl}?callId=abc`;
+    const postBody = "CallSid=CS778&CallStatus=completed&From=%2B15550000000";
+    const signature = twilioSignature({ authToken, url: urlWithQuery, postBody });
+
+    const first = verifyTwilioWebhook(
+      {
+        headers: {
+          host: "example.com",
+          "x-forwarded-proto": "https",
+          "x-twilio-signature": signature,
+          "i-twilio-idempotency-token": "idem-replay-a",
+        },
+        rawBody: postBody,
+        url: "http://local/voice/webhook?callId=abc",
+        method: "POST",
+        query: { callId: "abc" },
+      },
+      authToken,
+      { publicUrl },
+    );
+    const second = verifyTwilioWebhook(
+      {
+        headers: {
+          host: "example.com",
+          "x-forwarded-proto": "https",
+          "x-twilio-signature": signature,
+          "i-twilio-idempotency-token": "idem-replay-b",
+        },
+        rawBody: postBody,
+        url: "http://local/voice/webhook?callId=abc",
+        method: "POST",
+        query: { callId: "abc" },
+      },
+      authToken,
+      { publicUrl },
+    );
+
+    expect(first.ok).toBe(true);
+    expect(first.isReplay).toBe(false);
+    expect(first.verifiedRequestKey).toBeTruthy();
     expect(second.ok).toBe(true);
     expect(second.isReplay).toBe(true);
+    expect(second.verifiedRequestKey).toBe(first.verifiedRequestKey);
   });
 
   it("rejects invalid signatures even when attacker injects forwarded host", () => {
@@ -517,4 +603,20 @@ describe("verifyTwilioWebhook", () => {
     expect(result.ok).toBe(false);
     expect(result.verificationUrl).toBe("https://legitimate.example.com/voice/webhook");
   });
+
+  it("returns a stable request key when verification is skipped", () => {
+    const ctx = {
+      headers: {},
+      rawBody: "CallSid=CS123&CallStatus=completed",
+      url: "https://example.com/voice/webhook",
+      method: "POST" as const,
+    };
+    const first = verifyTwilioWebhook(ctx, "token", { skipVerification: true });
+    const second = verifyTwilioWebhook(ctx, "token", { skipVerification: true });
+
+    expect(first.ok).toBe(true);
+    expect(first.verifiedRequestKey).toMatch(/^twilio:skip:/);
+    expect(second.verifiedRequestKey).toBe(first.verifiedRequestKey);
+    expect(second.isReplay).toBe(true);
+  });
 });

package/src/webhook-security.ts

@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import { getHeader } from "./http-headers.js";
 import type { WebhookContext } from "./types.js";
 
 const REPLAY_WINDOW_MS = 10 * 60 * 1000;
@@ -29,6 +30,10 @@ function sha256Hex(input: string): string {
   return crypto.createHash("sha256").update(input).digest("hex");
 }
 
+function createSkippedVerificationReplayKey(provider: string, ctx: WebhookContext): string {
+  return `${provider}:skip:${sha256Hex(`${ctx.method}\n${ctx.url}\n${ctx.rawBody}`)}`;
+}
+
 function pruneReplayCache(cache: ReplayCache, now: number): void {
   for (const [key, expiresAt] of cache.seenUntil) {
     if (expiresAt <= now) {
@@ -81,17 +86,7 @@ export function validateTwilioSignature(
     return false;
   }
 
-  // Build the string to sign: URL + sorted params (key+value pairs)
-  let dataToSign = url;
-
-  // Sort params alphabetically and append key+value
-  const sortedParams = Array.from(params.entries()).toSorted((a, b) =>
-    a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0,
-  );
-
-  for (const [key, value] of sortedParams) {
-    dataToSign += key + value;
-  }
+  const dataToSign = buildTwilioDataToSign(url, params);
 
   // HMAC-SHA1 with auth token, then base64 encode
   const expectedSignature = crypto
@@ -103,6 +98,24 @@ export function validateTwilioSignature(
   return timingSafeEqual(signature, expectedSignature);
 }
 
+function buildTwilioDataToSign(url: string, params: URLSearchParams): string {
+  let dataToSign = url;
+  const sortedParams = Array.from(params.entries()).toSorted((a, b) =>
+    a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0,
+  );
+  for (const [key, value] of sortedParams) {
+    dataToSign += key + value;
+  }
+  return dataToSign;
+}
+
+function buildCanonicalTwilioParamString(params: URLSearchParams): string {
+  return Array.from(params.entries())
+    .toSorted((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+    .map(([key, value]) => `${key}=${value}`)
+    .join("&");
+}
+
 /**
  * Timing-safe string comparison to prevent timing attacks.
  */
@@ -353,20 +366,6 @@ function buildTwilioVerificationUrl(
   }
 }
 
-/**
- * Get a header value, handling both string and string[] types.
- */
-function getHeader(
-  headers: Record<string, string | string[] | undefined>,
-  name: string,
-): string | undefined {
-  const value = headers[name.toLowerCase()];
-  if (Array.isArray(value)) {
-    return value[0];
-  }
-  return value;
-}
-
 function isLoopbackAddress(address?: string): boolean {
   if (!address) {
     return false;
@@ -392,6 +391,8 @@ export interface TwilioVerificationResult {
   isNgrokFreeTier?: boolean;
   /** Request is cryptographically valid but was already processed recently. */
   isReplay?: boolean;
+  /** Stable request identity derived from signed Twilio material. */
+  verifiedRequestKey?: string;
 }
 
 export interface TelnyxVerificationResult {
@@ -399,19 +400,18 @@ export interface TelnyxVerificationResult {
   reason?: string;
   /** Request is cryptographically valid but was already processed recently. */
   isReplay?: boolean;
+  /** Stable request identity derived from signed Telnyx material. */
+  verifiedRequestKey?: string;
 }
 
 function createTwilioReplayKey(params: {
-  ctx: WebhookContext;
-  signature: string;
   verificationUrl: string;
+  signature: string;
+  requestParams: URLSearchParams;
 }): string {
-  const idempotencyToken = getHeader(params.ctx.headers, "i-twilio-idempotency-token");
-  if (idempotencyToken) {
-    return `twilio:idempotency:${idempotencyToken}`;
-  }
-  return `twilio:fallback:${sha256Hex(
-    `${params.verificationUrl}\n${params.signature}\n${params.ctx.rawBody}`,
+  const canonicalParams = buildCanonicalTwilioParamString(params.requestParams);
+  return `twilio:req:${sha256Hex(
+    `${params.verificationUrl}\n${canonicalParams}\n${params.signature}`,
   )}`;
 }
 
@@ -470,7 +470,14 @@ export function verifyTelnyxWebhook(
   },
 ): TelnyxVerificationResult {
   if (options?.skipVerification) {
-    return { ok: true, reason: "verification skipped (dev mode)" };
+    const replayKey = createSkippedVerificationReplayKey("telnyx", ctx);
+    const isReplay = markReplay(telnyxReplayCache, replayKey);
+    return {
+      ok: true,
+      reason: "verification skipped (dev mode)",
+      isReplay,
+      verifiedRequestKey: replayKey,
+    };
   }
 
   if (!publicKey) {
@@ -508,7 +515,7 @@ export function verifyTelnyxWebhook(
 
     const replayKey = `telnyx:${sha256Hex(`${timestamp}\n${signature}\n${ctx.rawBody}`)}`;
     const isReplay = markReplay(telnyxReplayCache, replayKey);
-    return { ok: true, isReplay };
+    return { ok: true, isReplay, verifiedRequestKey: replayKey };
   } catch (err) {
     return {
       ok: false,
@@ -560,7 +567,14 @@ export function verifyTwilioWebhook(
 ): TwilioVerificationResult {
   // Allow skipping verification for development/testing
   if (options?.skipVerification) {
-    return { ok: true, reason: "verification skipped (dev mode)" };
+    const replayKey = createSkippedVerificationReplayKey("twilio", ctx);
+    const isReplay = markReplay(twilioReplayCache, replayKey);
+    return {
+      ok: true,
+      reason: "verification skipped (dev mode)",
+      isReplay,
+      verifiedRequestKey: replayKey,
+    };
   }
 
   const signature = getHeader(ctx.headers, "x-twilio-signature");
@@ -583,13 +597,16 @@ export function verifyTwilioWebhook(
   // Parse the body as URL-encoded params
   const params = new URLSearchParams(ctx.rawBody);
 
-  // Validate signature
   const isValid = validateTwilioSignature(authToken, signature, verificationUrl, params);
 
   if (isValid) {
-    const replayKey = createTwilioReplayKey({ ctx, signature, verificationUrl });
+    const replayKey = createTwilioReplayKey({
+      verificationUrl,
+      signature,
+      requestParams: params,
+    });
     const isReplay = markReplay(twilioReplayCache, replayKey);
-    return { ok: true, verificationUrl, isReplay };
+    return { ok: true, verificationUrl, isReplay, verifiedRequestKey: replayKey };
   }
 
   // Check if this is ngrok free tier - the URL might have different format
@@ -619,6 +636,8 @@ export interface PlivoVerificationResult {
   version?: "v3" | "v2";
   /** Request is cryptographically valid but was already processed recently. */
   isReplay?: boolean;
+  /** Stable request identity derived from signed Plivo material. */
+  verifiedRequestKey?: string;
 }
 
 function normalizeSignatureBase64(input: string): string {
@@ -791,7 +810,14 @@ export function verifyPlivoWebhook(
   },
 ): PlivoVerificationResult {
   if (options?.skipVerification) {
-    return { ok: true, reason: "verification skipped (dev mode)" };
+    const replayKey = createSkippedVerificationReplayKey("plivo", ctx);
+    const isReplay = markReplay(plivoReplayCache, replayKey);
+    return {
+      ok: true,
+      reason: "verification skipped (dev mode)",
+      isReplay,
+      verifiedRequestKey: replayKey,
+    };
   }
 
   const signatureV3 = getHeader(ctx.headers, "x-plivo-signature-v3");
@@ -849,7 +875,7 @@ export function verifyPlivoWebhook(
     }
     const replayKey = `plivo:v3:${sha256Hex(`${verificationUrl}\n${nonceV3}`)}`;
     const isReplay = markReplay(plivoReplayCache, replayKey);
-    return { ok: true, version: "v3", verificationUrl, isReplay };
+    return { ok: true, version: "v3", verificationUrl, isReplay, verifiedRequestKey: replayKey };
   }
 
   if (signatureV2 && nonceV2) {
@@ -869,7 +895,7 @@ export function verifyPlivoWebhook(
     }
     const replayKey = `plivo:v2:${sha256Hex(`${verificationUrl}\n${nonceV2}`)}`;
     const isReplay = markReplay(plivoReplayCache, replayKey);
-    return { ok: true, version: "v2", verificationUrl, isReplay };
+    return { ok: true, version: "v2", verificationUrl, isReplay, verifiedRequestKey: replayKey };
   }
 
   return {

package/src/webhook.test.ts

@@ -7,7 +7,7 @@ import { VoiceCallWebhookServer } from "./webhook.js";
 
 const provider: VoiceCallProvider = {
   name: "mock",
-  verifyWebhook: () => ({ ok: true }),
+  verifyWebhook: () => ({ ok: true, verifiedRequestKey: "mock:req:base" }),
   parseWebhookEvent: () => ({ events: [] }),
   initiateCall: async () => ({ providerCallId: "provider-call", status: "initiated" }),
   hangupCall: async () => {},
@@ -123,7 +123,7 @@ describe("VoiceCallWebhookServer replay handling", () => {
   it("acknowledges replayed webhook requests and skips event side effects", async () => {
     const replayProvider: VoiceCallProvider = {
       ...provider,
-      verifyWebhook: () => ({ ok: true, isReplay: true }),
+      verifyWebhook: () => ({ ok: true, isReplay: true, verifiedRequestKey: "mock:req:replay" }),
       parseWebhookEvent: () => ({
         events: [
           {
@@ -165,4 +165,89 @@ describe("VoiceCallWebhookServer replay handling", () => {
       await server.stop();
     }
   });
+
+  it("passes verified request key from verifyWebhook into parseWebhookEvent", async () => {
+    const parseWebhookEvent = vi.fn((_ctx: unknown, options?: { verifiedRequestKey?: string }) => ({
+      events: [
+        {
+          id: "evt-verified",
+          dedupeKey: options?.verifiedRequestKey,
+          type: "call.speech" as const,
+          callId: "call-1",
+          providerCallId: "provider-call-1",
+          timestamp: Date.now(),
+          transcript: "hello",
+          isFinal: true,
+        },
+      ],
+      statusCode: 200,
+    }));
+    const verifiedProvider: VoiceCallProvider = {
+      ...provider,
+      verifyWebhook: () => ({ ok: true, verifiedRequestKey: "verified:req:123" }),
+      parseWebhookEvent,
+    };
+    const { manager, processEvent } = createManager([]);
+    const config = createConfig({ serve: { port: 0, bind: "127.0.0.1", path: "/voice/webhook" } });
+    const server = new VoiceCallWebhookServer(config, manager, verifiedProvider);
+
+    try {
+      const baseUrl = await server.start();
+      const address = (
+        server as unknown as { server?: { address?: () => unknown } }
+      ).server?.address?.();
+      const requestUrl = new URL(baseUrl);
+      if (address && typeof address === "object" && "port" in address && address.port) {
+        requestUrl.port = String(address.port);
+      }
+      const response = await fetch(requestUrl.toString(), {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: "CallSid=CA123&SpeechResult=hello",
+      });
+
+      expect(response.status).toBe(200);
+      expect(parseWebhookEvent).toHaveBeenCalledTimes(1);
+      expect(parseWebhookEvent.mock.calls[0]?.[1]).toEqual({
+        verifiedRequestKey: "verified:req:123",
+      });
+      expect(processEvent).toHaveBeenCalledTimes(1);
+      expect(processEvent.mock.calls[0]?.[0]?.dedupeKey).toBe("verified:req:123");
+    } finally {
+      await server.stop();
+    }
+  });
+
+  it("rejects requests when verification succeeds without a request key", async () => {
+    const parseWebhookEvent = vi.fn(() => ({ events: [], statusCode: 200 }));
+    const badProvider: VoiceCallProvider = {
+      ...provider,
+      verifyWebhook: () => ({ ok: true }),
+      parseWebhookEvent,
+    };
+    const { manager } = createManager([]);
+    const config = createConfig({ serve: { port: 0, bind: "127.0.0.1", path: "/voice/webhook" } });
+    const server = new VoiceCallWebhookServer(config, manager, badProvider);
+
+    try {
+      const baseUrl = await server.start();
+      const address = (
+        server as unknown as { server?: { address?: () => unknown } }
+      ).server?.address?.();
+      const requestUrl = new URL(baseUrl);
+      if (address && typeof address === "object" && "port" in address && address.port) {
+        requestUrl.port = String(address.port);
+      }
+      const response = await fetch(requestUrl.toString(), {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: "CallSid=CA123&SpeechResult=hello",
+      });
+
+      expect(response.status).toBe(401);
+      expect(parseWebhookEvent).not.toHaveBeenCalled();
+    } finally {
+      await server.stop();
+    }
+  });
 });

package/src/webhook.ts

@@ -15,6 +15,7 @@ import type { VoiceCallProvider } from "./providers/base.js";
 import { OpenAIRealtimeSTTProvider } from "./providers/stt-openai-realtime.js";
 import type { TwilioProvider } from "./providers/twilio.js";
 import type { NormalizedEvent, WebhookContext } from "./types.js";
+import { startStaleCallReaper } from "./webhook/stale-call-reaper.js";
 
 const MAX_WEBHOOK_BODY_BYTES = 1024 * 1024;
 
@@ -28,7 +29,7 @@ export class VoiceCallWebhookServer {
   private manager: CallManager;
   private provider: VoiceCallProvider;
   private coreConfig: CoreConfig | null;
-  private staleCallReaperInterval: ReturnType<typeof setInterval> | null = null;
+  private stopStaleCallReaper: (() => void) | null = null;
 
   /** Media stream handler for bidirectional audio (when streaming enabled) */
   private mediaStreamHandler: MediaStreamHandler | null = null;
@@ -217,48 +218,21 @@ export class VoiceCallWebhookServer {
         resolve(url);
 
         // Start the stale call reaper if configured
-        this.startStaleCallReaper();
+        this.stopStaleCallReaper = startStaleCallReaper({
+          manager: this.manager,
+          staleCallReaperSeconds: this.config.staleCallReaperSeconds,
+        });
       });
     });
   }
 
-  /**
-   * Start a periodic reaper that ends calls older than the configured threshold.
-   * Catches calls stuck in unexpected states (e.g., notify-mode calls that never
-   * receive a terminal webhook from the provider).
-   */
-  private startStaleCallReaper(): void {
-    const maxAgeSeconds = this.config.staleCallReaperSeconds;
-    if (!maxAgeSeconds || maxAgeSeconds <= 0) {
-      return;
-    }
-
-    const CHECK_INTERVAL_MS = 30_000; // Check every 30 seconds
-    const maxAgeMs = maxAgeSeconds * 1000;
-
-    this.staleCallReaperInterval = setInterval(() => {
-      const now = Date.now();
-      for (const call of this.manager.getActiveCalls()) {
-        const age = now - call.startedAt;
-        if (age > maxAgeMs) {
-          console.log(
-            `[voice-call] Reaping stale call ${call.callId} (age: ${Math.round(age / 1000)}s, state: ${call.state})`,
-          );
-          void this.manager.endCall(call.callId).catch((err) => {
-            console.warn(`[voice-call] Reaper failed to end call ${call.callId}:`, err);
-          });
-        }
-      }
-    }, CHECK_INTERVAL_MS);
-  }
-
   /**
    * Stop the webhook server.
    */
   async stop(): Promise<void> {
-    if (this.staleCallReaperInterval) {
-      clearInterval(this.staleCallReaperInterval);
-      this.staleCallReaperInterval = null;
+    if (this.stopStaleCallReaper) {
+      this.stopStaleCallReaper();
+      this.stopStaleCallReaper = null;
     }
     return new Promise((resolve) => {
       if (this.server) {
@@ -341,9 +315,17 @@ export class VoiceCallWebhookServer {
       res.end("Unauthorized");
       return;
     }
+    if (!verification.verifiedRequestKey) {
+      console.warn("[voice-call] Webhook verification succeeded without request identity key");
+      res.statusCode = 401;
+      res.end("Unauthorized");
+      return;
+    }
 
     // Parse events
-    const result = this.provider.parseWebhookEvent(ctx);
+    const result = this.provider.parseWebhookEvent(ctx, {
+      verifiedRequestKey: verification.verifiedRequestKey,
+    });
 
     // Process each event
     if (verification.isReplay) {