VoxyWatch integration guide

VoxyWatch receives HEP (Homer Encapsulation Protocol) packets — it does not mirror traffic by itself. Your SBC or media server must be configured to send HEP to VoxyWatch's IP and port. This guide covers installation, the ports involved, and how to point the most common SBCs at VoxyWatch.

📦 Full release notes, packages and GPG signatures: github.com/VoxyWatch/publish

Quick install

One command installs everything. It auto-detects your distro (Debian 11+, Ubuntu 20.04+, RHEL / CentOS / Rocky / AlmaLinux 8+) and installs the correct package:

curl -fsSL https://raw.githubusercontent.com/VoxyWatch/publish/main/install.sh | sudo bash

After installation, open the portal at http://YOUR-IP:3080. The default login is admin / voxywatch (you must change it on first login). No license needed to start: the free tier gives you up to 50 concurrent calls and 1,000 CDRs. When you outgrow it, buy a license and drop in the .key file.

Activate a license

Get your Hardware ID (needed when purchasing) with node /opt/voxywatch/get-hwid.js, or find it in Settings → License. Then:

# Copy your license file into the config directory
cp voxywatch.key /etc/voxywatch/license.key
chown root:voxywatch /etc/voxywatch/license.key
chmod 640 /etc/voxywatch/license.key

No restart required — the portal picks it up within seconds. Manual packages and GPG verification are documented on GitHub.

Manual install & verification

Prefer to install by hand? Download the package for your distro from the v2.69.0 release:

# Debian / Ubuntu
curl -fsSL https://github.com/VoxyWatch/publish/releases/download/v2.69.0/voxywatch_2.69.0_amd64.deb -O
sudo dpkg -i voxywatch_2.69.0_amd64.deb

# RHEL / CentOS / Rocky / AlmaLinux
curl -fsSL https://github.com/VoxyWatch/publish/releases/download/v2.69.0/voxywatch-2.69.0-1.x86_64.rpm -O
sudo rpm -Uvh voxywatch-2.69.0-1.x86_64.rpm

Verify the package signature (GPG)

Every release is signed. To verify before installing:

# Import the release signing key (first time only)
curl -fsSL https://raw.githubusercontent.com/VoxyWatch/publish/main/voxywatch-release.gpg.pub | gpg --import

# Download package + signature, then verify
curl -fsSL https://github.com/VoxyWatch/publish/releases/download/v2.69.0/voxywatch_2.69.0_amd64.deb.asc -O
gpg --verify voxywatch_2.69.0_amd64.deb.asc voxywatch_2.69.0_amd64.deb

Signing key fingerprint: 80ED E252 3760 E622 FB97 BC15 4B21 BBC5 F215 26E3 — VoxyWatch (Release Signing Key) <releases@voxywatch.com>. SHA-256 checksums are in SHA256SUMS on the release page.

What's installed

File layout: /opt/voxywatch/ (binaries, read-only) · /etc/voxywatch/ (config + license key) · /var/lib/voxywatch/ (database, captures & audio — preserved on upgrade).

Manage the services

# Status
systemctl status voxywatch voxywatch-sniffer

# Logs
journalctl -fu voxywatch
journalctl -fu voxywatch-sniffer

# Restart
systemctl restart voxywatch voxywatch-sniffer

Upgrade

The portal shows an update banner when a new version is available — click Update now and it downloads, installs and restarts itself. To upgrade manually, re-run the install command above.

Ports & firewall

# Open the firewall (ufw)
ufw allow 3080/tcp        # portal
ufw allow 9060/udp        # HEP primary
ufw allow 9060/tcp        # HEP TCP
ufw allow 9910/udp        # HEP extra
ufw allow 9911/udp        # HEP extra

SBC integration

Point each platform's HEP exporter at VOXYWATCH_IP:9060. Replace 10.10.1.50 below with your VoxyWatch server IP. Use a unique capture-id per device so you can tell sources apart in the portal.

Asterisk

Two ways to feed Asterisk traffic into VoxyWatch. Pick the one that matches your setup — many users start with Option B because it captures audio too.

Option A — Native HEP (signaling only)

Asterisk has shipped native HEP since version 12, via res_hep.so. This captures SIP signaling only — to also capture RTP audio you'll need RTPEngine, HEPlify, or our probe (Option B). Create /etc/asterisk/hep.conf:

[general]
enabled = yes
capture_address = 10.10.1.50:9060   ; VoxyWatch IP:port
capture_id = 100                    ; unique per Asterisk instance
uuid_type = call-id

# Make sure the module is loaded, then reload
asterisk -rx "module show like hep"
asterisk -rx "module reload res_hep.so"
asterisk -rx "hep show"

Option B — voxywatch-probe (signaling + audio, recommended)

Our lightweight capture agent (github.com/VoxyWatch/voxywatch-probe) sniffs SIP, RTP and RTCP straight off the network interface and forwards them as HEP v3. It's a single Go binary plus libpcap, runs as a systemd service, and supports both amd64 and arm64 (on-premise, AWS Graviton, GCP).

Three reasons we recommend it for Asterisk:

• It does not modify Asterisk. The probe captures passively from the network — like tcpdump. Zero risk to your call routing, no config changes in pjsip.conf or hep.conf required.
• It reconstructs the call audio — something Asterisk's native HEP does not provide. You get full SIPREC-style stereo playback in the VoxyWatch portal.
• It works on any Asterisk version, including very old installs that predate res_hep.so.

Install on the Asterisk server (replace YOUR_VOXYWATCH with your VoxyWatch IP or hostname):

curl -fsSL https://raw.githubusercontent.com/VoxyWatch/voxywatch-probe/master/install.sh | sudo bash -s -- --server YOUR_VOXYWATCH:9060

The installer detects the CPU architecture, downloads the right binary, grants it capture permissions (CAP_NET_RAW), auto-detects the network interface, and leaves it running as a service that starts on boot. Verify:

systemctl status voxywatch-probe
journalctl -u voxywatch-probe -f     # look for: [stats] sip=.. rtp=.. sent=..

Then place a test call and confirm it appears in the VoxyWatch portal with audio.

The repo includes a detailed Asterisk guide at docs/sbc/asterisk.md with troubleshooting, interface selection, and advanced flags.

Kamailio

Native via the siptrace module. Mirror HEP directly to VoxyWatch in kamailio.cfg:

loadmodule "siptrace.so"

modparam("siptrace", "trace_on", 1)
modparam("siptrace", "hep_mode_on", 1)
modparam("siptrace", "hep_version", 3)
modparam("siptrace", "duplicate_uri", "sip:10.10.1.50:9060")
modparam("siptrace", "hep_capture_id", 200)

request_route {
    sip_trace();
    # ... routing ...
}

⚙ Alternative: if native HEP isn't available or you want full audio capture without touching Kamailio config, install voxywatch-probe on the Kamailio server — passive NIC capture, no config changes, captures audio too. See probe quick install.

FreeSWITCH

Native via mod_hep. Load the module, then create autoload_configs/hep.conf.xml:

<configuration name="hep.conf" description="HEP Config">
  <settings>
    <param name="capture-address" value="10.10.1.50"/>
    <param name="capture-port"    value="9060"/>
    <param name="hep-version"     value="3"/>
    <param name="capture-id"      value="300"/>
    <param name="enable-sip"  value="true"/>
    <param name="enable-rtcp" value="true"/>
  </settings>
</configuration>

fs_cli -x "reload mod_hep"
fs_cli -x "hep status"

⚙ Alternative: if native HEP isn't available or you want full audio capture without touching FreeSWITCH config, install voxywatch-probe on the FreeSWITCH server — passive NIC capture, no config changes, captures audio too. See probe quick install.

AudioCodes Mediant

Native via the SBC Mirror feature (firmware 7.20+). In the Web GUI go to Troubleshooting → SBC Mirror and add an entry: Mirror Type HEP, server 10.10.1.50, port 9060, version 3, capture ID 600. Or via INI:

[SBCMirror]
FORMAT SBCMirror_Index = SBCMirrorMode, SBCMirrorDestIP, SBCMirrorDestPort, SBCMirrorVersion, SBCMirrorCaptureID
SBCMirror 0 = 1, 10.10.1.50, 9060, 3, 600
[ \SBCMirror ]

⚙ Alternative: if native HEP isn't available or you want full audio capture without touching AudioCodes Mediant config, install voxywatch-probe on the AudioCodes Mediant server — passive NIC capture, no config changes, captures audio too. See probe quick install.

Sansay VSXi

Recent Sansay VSXi software supports HEP natively. In the Sansay configuration, add a TAP entry pointing at VoxyWatch and set the protocol to HEP:

TAP[1]
filterDnis=*
signalingIp=10.10.1.50    ; VoxyWatch IP
signalingPort=9060
protocol=HEP
expires=1800

Use filterDnis=* to capture all calls, or set a specific DNIS pattern to capture a subset. Once applied, test calls appear in VoxyWatch within seconds.

⚙ Alternative: if native HEP isn't available or you want full audio capture without touching Sansay VSXi config, install voxywatch-probe on the Sansay VSXi server — passive NIC capture, no config changes, captures audio too. See probe quick install.

HEPlify (universal sidecar)

For any platform without native HEP (e.g. Cisco CUBE), run HEPlify on a server that sees the SIP traffic (SPAN/TAP port) and forward as HEP3:

# Download
wget https://github.com/sipcapture/heplify/releases/latest/download/heplify-linux-amd64
chmod +x heplify-linux-amd64 && mv heplify-linux-amd64 /usr/local/bin/heplify

# Capture SIP + RTCP (recommended — avoids RTP flood)
heplify -i eth0 -hs 10.10.1.50:9060 -m SIPRTCP -id 1000

voxywatch-probe — capture from anywhere

VoxyWatch ships with an optional lightweight capture agent, voxywatch-probe (Go + libpcap, amd64 & arm64). It sniffs SIP/RTP/RTCP straight off the NIC and forwards HEP v3 to your VoxyWatch server. Use it when your SBC can't emit HEP natively, or as a drop-in HEPlify replacement.

Install on the PBX/SBC server (passive sniffing, never touches your config):

curl -fsSL https://raw.githubusercontent.com/VoxyWatch/voxywatch-probe/master/install.sh | sudo bash -s -- --server YOUR_VOXYWATCH:9060

The installer detects the architecture, downloads the binary, grants it capture permissions, auto-detects the interface, and leaves it running as a systemd service that starts on boot. Verify with systemctl status voxywatch-probe and journalctl -fu voxywatch-probe — you should see [stats] sip=.. rtp=.. sent=...

Full SBC compatibility matrix and per-model guides: github.com/VoxyWatch/voxywatch-probe/docs/sbc.

SNMP agent & traps

VoxyWatch embeds its own SNMP agent (v2c + v3) so PRTG, Zabbix, Nagios and similar NMS can poll it and receive edge-triggered traps. The same thresholds drive the header notification bell and the SNMP traps, so they always agree.

What it exposes: 30+ OIDs covering host (CPU, RAM, disk), capture (sources, packets, drops), VoIP KPIs (ASR, NER, MOS, jitter, loss) and bottleneck diagnostics.

Traps are fired only on state transitions (no spam) for: capture loss, sniffer down, no sources, low ASR, low MOS, RTP/kernel drops, disk/RAM/CPU high.

Download the MIB and configure community/v3 credentials in Settings → SNMP. Default port: UDP/161 (agent), UDP/162 (trap destination).

🚨 Incidents & the agentic NOC

Every anomaly VoxyWatch detects — trunk degradation, capture loss, sniffer down, silent HEP sources, system bottlenecks, global traffic drops, low audio retention — becomes a persistent incident with a lifecycle (open → acknowledged → resolved), deduplication (one live incident per problem, no alert storms), an auditable timeline, and stability-based auto-resolve.

A dedicated Incidents tab gives you filters, a detail view, and one-click actions. The open-incident badge appears in the nav and the notification bell.

Autonomous investigation

The moment an incident opens, VoxyWatch investigates by itself — no human, no LLM needed yet: sample failing calls, dominant SIP failure codes, failing IP paths, affected destinations, and whether other trunks degraded at the same time (the local-vs-carrier tell). With an LLM key configured, an AI investigator with live tools produces a structured diagnosis: probable root cause, confidence, scope, recommended action — citing the evidence. Budgeted and cached so it can't run up your token bill.

Runbooks & case memory

VoxyWatch ships with field runbooks (low ASR, packet loss, capture down, traffic drop) that the investigator follows and cites step by step. Add your own as JSON. When you resolve an incident and write down the cause, that resolution becomes institutional memory — the next time the same pattern fires, the diagnosis references it.

Statistical confidence

Declaring CRITICAL requires earning it: a minimum sample of calls, measurement coverage for quality metrics, deviation from the trunk's own baseline, and sustained degradation across consecutive evaluations. Validated against production incidents: −92% critical noise versus naive thresholds — without losing a single record.

Safe remediation

Proposed actions come from a closed, code-level catalog (restart the capture sniffer, recompute baselines — never your SBC), execute only after your explicit approval, and land in the incident timeline with who-approved-what.

📲 Telegram & email notifications

Critical incidents reach your phone with the diagnosis attached and inline action buttons: ✅ Ack · ✔ Resolve · 🔍 Investigate · plus the proposed remediation when one applies.

Per-user setup (2 minutes)

1. Your team creates one Telegram bot for the installation — a guided wizard in Settings → Notifications walks you through it.
2. Each portal user links their own chat with a one-time code — no tokens to share, no chat IDs to hunt down.
3. Each user picks their minimum severity and opts into the scheduled digest.

Every action taken from Telegram is audited under the real portal username and gated by role — viewers receive read-only notifications. An optional NOC-room group chat receives everything.

Email

Incidents can also arrive by email: global SMTP with Gmail / Microsoft 365 presets, a step-by-step in-product guide and a live test button.

Digest

A daily or weekly digest (incidents, trunk health, volume vs the previous period, capacity forecast) lands in Telegram or your webhook on schedule — or on demand via API.

🔗 MCP server

VoxyWatch ships a standalone Model Context Protocol server (voxywatch-mcp.js): connect Claude Desktop, Claude Code or any MCP-compatible agent and let it query health, KPIs, trunk status, CDRs and incidents — with evidence and diagnosis — through 6 read-only tools.

Authenticated with the same scoped API keys as the Integration API. Your corporate AI can now interrogate your voice network.

🔒 PCI-DSS audio suppression

VoxyWatch is built for environments that handle payments by phone (call centers, IVRs taking card numbers, etc.). The Probe can drop the RTP of a payment window at the source, so sensitive audio (card / CVV) never leaves the secure environment, never travels the network, never reaches VoxyWatch. This is the strictest option — smallest possible PCI scope.

How it works

The Probe hot-reloads a JSON file listing RTP SSRCs to suppress. Any RTP packet matching a listed SSRC is dropped before being sent to VoxyWatch.

{
  "suppress": [
    { "ssrc": "0xa1b2c3d4", "until": "2026-06-10T15:30:00Z" },
    { "ssrc": "0x12345678" }
  ]
}

• Default path: /etc/voxywatch-probe/pci_suppress.json
• Custom path: environment variable VW_PROBE_PCI_FILE
• Reload: edit the file → Probe applies within seconds. No restart required.
• Empty or missing file: no suppression (feature effectively disabled).

Typical call-center workflow

1. Agent clicks "Pause recording" in their CRM when the customer is about to dictate the card.
2. The CRM adds the current call's RTP SSRC to pci_suppress.json with an expiration timestamp.
3. The Probe stops sending that audio stream immediately.
4. When the customer finishes, the agent clicks "Resume" — the entry expires or is removed.
5. Recording continues normally for the rest of the call.

The card / CVV portion was never on the network and never written to disk.

Defense in depth

The probe-side suppression pairs with a complementary suppression layer at the portal / sniffer level — so even if a Probe entry is misconfigured, the portal can still drop the same SSRC server-side before storage. Two-layer protection for production deployments.

Reference: the voxywatch-probe README has the canonical specification of this feature.

Server sizing calculator

Use the interactive calculator below to estimate the hardware you need based on your call volume, whether you capture audio, and retention window. Reference numbers — for production peaks dimension up.

NOC AI copilot

The built-in copilot reads the trunk's current KPIs, alarms, learned baseline and 48h trend, and writes back the probable cause and the NOC action — in plain language. It only explains and recommends; it never touches the SBC.

Bring your own key. Configure your provider in Settings → AI:

• OpenAI — GPT-4o / GPT-4o-mini / o1
• Anthropic — Claude Sonnet / Opus
• Google — Gemini 1.5 / 2.0
• OpenRouter — any model from the OpenRouter catalog

Responses are cached server-side to control token spend. The copilot is bilingual (EN / ES) and turned off until you enable it; nothing is sent anywhere by default.

Per-trunk copilot answers one trunk at a time. NOC summary copilot prioritises and groups all alarming trunks across the estate and suggests an action per group.

Integration API /api/v1

Read-only versioned REST API for billing and monitoring systems. Stable public schema, decoupled from internals.

Endpoints: CDR search and single CDR, SIP-trace JSON, PCAP and audio download.

Auth. API keys (hashed at rest) with per-key scopes: cdr:read, trace:read, audio:read. Per-key IP allowlists and rate limits. Errors follow RFC 9457 application/problem+json. OpenAPI spec available from the portal.

Manage keys in Settings → API keys. Example:

curl -H "Authorization: Bearer YOUR_KEY" \
     https://YOUR-VOXYWATCH:3080/api/v1/cdr?from=2026-06-01&to=2026-06-07&carrier=acme

Troubleshooting

VoxyWatch shows no packets

# Are packets even arriving?
tcpdump -i any udp port 9060 -n -c 20

# Is the sniffer running and bound?
systemctl status voxywatch-sniffer
journalctl -u voxywatch-sniffer | grep "UDP\|TCP"

Packets arrive but no SIP data

Check for a HEP version mismatch — set the SBC to HEPv3 (VoxyWatch auto-detects from the magic bytes). If trusted_prefixes is set in Settings, make sure the SBC IP matches, or set it to empty to accept from any source.

No RTP quality stats

RTP quality needs RTCP packets via HEP (low bandwidth, preferred). Enable RTCP on your SBC — for RTPEngine add RTCP to homer-capture; for Asterisk load res_hep_rtcp.so.

Audio reconstruction fails

Reconstruction needs SIPREC RTP streams in the capture and has_audio = true on the CDR. Verify python3 --version and disk space in /var/lib/voxywatch/.

Abrechnung, Zahlungen & Kündigungen

Zahlungen, Zahlungsnachweise und Kündigungen der VoxyWatch-Lizenzen werden von Paddle.com, unserem Zahlungsanbieter, abgewickelt. Paddle ist bei jedem Kauf der Merchant of Record (MoR).

Um Ihre Mitgliedschaft zu verwalten — kündigen, Zahlungsmethode aktualisieren oder Rechnungen herunterladen — nutzen Sie das Paddle-Kundenportal:

Paddle-Kundenportal öffnen

Melden Sie sich mit der beim Kauf verwendeten E-Mail an (Magic-Link, kein Passwort nötig).

Abonnement kündigen

Wenn Sie im Portal kündigen, wird die Kündigung zum Ende Ihres aktuellen Abrechnungszeitraums geplant. Ihre Lizenz bleibt bis zum nächsten Verlängerungsdatum aktiv und wird danach nicht erneuert. Beim Ablauf einer Lizenz werden keine Daten gelöscht.

Rückerstattungen

Rückerstattungsanträge werden gemäß unserer Rückerstattungsrichtlinie bearbeitet. Da Paddle der Merchant of Record ist, werden Rückerstattungen über Paddle ausgestellt.