Webhook signature and forwarding-header security, plus the CLI, agent tool, and Gateway RPC surfaces. Part of the Voice call plugin guide.

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:

Additional protections:

• Webhook replay protection is enabled for Twilio, Telnyx, and Plivo. Replayed valid webhook requests are acknowledged but skipped for side effects.
• Twilio conversation turns include a per-turn token in <Gather> callbacks, so stale/replayed speech callbacks cannot satisfy a newer pending transcript turn.
• Unauthenticated webhook requests are rejected before body reads when the provider's required signature headers are missing.
• The voice-call webhook uses the shared pre-auth body-read profile (64 KB max body, 5-second read timeout) plus a per-key in-flight cap (8 concurrent requests per key by default) before signature verification.

Example with a stable public host:

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          publicUrl: "https://voice.example.com/voice/webhook",
          webhookSecurity: {
            allowedHosts: ["voice.example.com"],
          },
        },
      },
    },
  },
}

CLI

apus voicecall call --to "+15555550123" --message "Hello from Apus"
apus voicecall start --to "+15555550123"   # alias for call
apus voicecall continue --call-id <id> --message "Any questions?"
apus voicecall speak --call-id <id> --message "One moment"
apus voicecall dtmf --call-id <id> --digits "ww123456#"
apus voicecall end --call-id <id>
apus voicecall status --call-id <id>
apus voicecall tail
apus voicecall latency                      # summarize turn latency from logs
apus voicecall expose --mode funnel

When the Gateway is already running, operational voicecall commands delegate to the Gateway-owned voice-call runtime so the CLI does not bind a second webhook server. If no Gateway is reachable, the commands fall back to a standalone CLI runtime. After printing the call result, that process keeps serving its webhook until SIGINT or SIGTERM. Shutdown joins runtime creation, accepted command work, and pending reaper hangups before closing its resources.

latency reads persisted call records from SQLite by default. Use --file <path> to read an existing custom JSONL log (with a basename other than calls.jsonl) and --last <n> to limit analysis to the last N records (default 200). Output includes min/max/avg, p50, and p95 for turn latency and listen-wait times.

Voice Call JSONL logs are retired pre-July state. Upgrade through Apus 2026.9.7 and run apus doctor --fix to import them into SQLite before updating. That release preserves call data, event ordering, and the original log as calls.jsonl.migrated. Current Doctor preserves any remaining source and reports the intermediate upgrade; runtime reads only canonical SQLite.

Calls retain the agent selected when they were created. Changing the configured agent affects new calls. Older active records without an explicit agentId are not resumed automatically, even if a session key names an agent. Their stored rows and transcripts remain unchanged; hang up any remaining call at the provider and start a new call. Completed history remains readable without an agent owner.

Agent tool

Tool name: voice_call.

The voice-call plugin ships a matching agent skill.

Gateway RPC

dtmfSequence is only valid with mode: "conversation"; notify-mode calls should use voicecall.dtmf after the call exists if they need post-connect digits.