Notifications

Alert notifications

Vantyr can deliver alert-rule matches to external notification channels. When an alert rule fires - a URL/keystroke/category content match, a CPU/memory/disk resource threshold, or an agent-offline event - the server fans the alert out to every configured channel at once.

Supported channels:

Channel	What it does
Email (SMTP)	Sends an email through any SMTP server.
Slack	Posts to a Slack channel via an Incoming Webhook.
Discord	Posts to a Discord channel via a channel Webhook.
Microsoft Teams	Posts to a Teams channel via an Incoming Webhook / Workflow.
Telegram	Sends a message to a chat through a bot.
ntfy	Pushes to an ntfy topic (ntfy.sh or self-hosted).
Pushover	Sends a push to your devices via Pushover.
Webhook	POSTs the raw alert JSON to any HTTP endpoint.
Home Assistant	Fires a custom event for HA automations - see Home Assistant.

All channels are optional and off by default. Vantyr boots normally with none configured; alerts are still recorded to the Events feed regardless.

---

How it works

• Channels are configured with server environment variables (see below). Set the variables for the channels you want, then restart the server/container.
• Secrets (SMTP passwords, webhook URLs, bot tokens) live only on the server - they are never stored in the database and are never returned to the browser.
• Each configured channel is registered at startup. A channel whose required variables are missing is simply skipped (a line is logged explaining why).
• Delivery is fire-and-forget off the alert hot path: a failed send is logged (warn) without blocking alerting, and a per-(rule, agent) cooldown prevents notification spam.
• Implementation lives in server/src/notify/ (one module per channel).

---

Manage from the dashboard

Open Settings → Alert notification channels (admin only). The card shows:

• every channel with a Configured / Not configured badge,
• the exact environment variables each channel needs, with setup links, and
• a Send test notification button that fires a sample alert through every configured channel and reports per-channel success/failure - the quickest way to confirm your setup end-to-end.

The status endpoint never returns secrets; the test action is admin-only and audited (notifications.test).

---

Channel reference

Set these on the Vantyr server (see Configuration and the Environment template), then restart. These variables are read with plain env::var and do not support the _FILE secret-file variant.

Email (SMTP)

Variable	Required	Default	Notes
SMTP_HOST	yes	-	SMTP server hostname, e.g. smtp.gmail.com.
SMTP_FROM	yes	-	Sender, e.g. Vantyr <alerts@example.com> or alerts@example.com.
SMTP_TO	yes	-	Comma-separated recipients, e.g. ops@example.com,oncall@example.com.
SMTP_PORT	no	per TLS mode	Defaults to 587 (STARTTLS), 465 (implicit), or 25 (none).
SMTP_USERNAME	no	-	Omit for an unauthenticated relay.
SMTP_PASSWORD	no	-	App password / SMTP credential.
SMTP_TLS	no	starttls	starttls · implicit (TLS-on-connect, e.g. port 465) · none (plaintext - avoid).
SMTP_SUBJECT_PREFIX	no	-	Optional string prepended to every subject, e.g. [Vantyr].

SMTP_HOST, SMTP_FROM, and SMTP_TO are all required for the email channel to register. With most providers you'll create an app password rather than using your account password.

Slack

1. In Slack, create (or open) an app → Incoming Webhooks → Add New Webhook to Workspace, pick the channel, and copy the https://hooks.slack.com/services/… URL.
2. Set SLACK_WEBHOOK_URL to that URL.

Also works with Slack-compatible receivers (e.g. Mattermost).

Discord

1. In Discord: Channel → Edit Channel → Integrations → Webhooks → New Webhook, then Copy Webhook URL.
2. Set DISCORD_WEBHOOK_URL to that URL.

Microsoft Teams

1. In Teams, add an Incoming Webhook connector to the channel (or a Workflows "Post to a channel when a webhook request is received" flow) and copy the URL.
2. Set TEAMS_WEBHOOK_URL to that URL.

Telegram

1. Create a bot with @BotFather and copy the bot token.
2. Start a chat with the bot (or add it to a group/channel), then find the chat id (e.g. message the bot and read https://api.telegram.org/bot<TOKEN>/getUpdates).
3. Set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID (numeric id, or @channelusername).

ntfy

Variable	Required	Notes
NTFY_URL	yes	The full topic URL, e.g. https://ntfy.sh/vantyr-alerts or your self-hosted https://ntfy.example.com/alerts.
NTFY_TOKEN	no	Access token, only for protected topics (sent as a Bearer token).

Pushover

1. Create an application at pushover.net to get an API token, and copy your user key from the dashboard.
2. Set PUSHOVER_TOKEN and PUSHOVER_USER_KEY.

Generic webhook

POSTs the raw alert JSON (see What gets sent) to any endpoint - wire alerts into your own automation, SIEM, or chat bridge.

Variable	Required	Notes
NOTIFY_WEBHOOK_URL	yes	http(s):// endpoint that receives the alert payload as JSON.
NOTIFY_WEBHOOK_AUTH_HEADER	no	A full Header: value pair (e.g. X-Api-Key: secret), or a bare value sent as Authorization.

Home Assistant

Fires a custom event into Home Assistant so HA automations decide how to react (mobile push, TTS, lights). This has its own deep-dive with a ready-made blueprint: Home Assistant.

---

What gets sent

Most channels render a short, human-readable message:

• Title: Vantyr: {rule_name}
• Body: {agent_name} ({channel}): {snippet} - where channel is a friendly label (URL, Keystrokes, URL category, Resource, Agent offline).
• Deep link: when PUBLIC_BASE_URL is set, messages link straight to the agent's Activity timeline at the event time.

The Webhook and Home Assistant channels instead send the full structured payload:

Field	Description
event_id	DB id of the stored alert event.
rule_id / rule_name	The alert rule that matched.
channel	The channel that triggered (url, keys, url_category, resource, agent_offline).
agent_id / agent_name	The agent that produced the match.
snippet	The matched text / threshold summary.
ts	Match timestamp (epoch seconds).
dashboard_url	Deep link to the agent (only when PUBLIC_BASE_URL is set).
dashboard_activity_url	Deep link to the agent Activity timeline at the event time (only when PUBLIC_BASE_URL is set).

---

Troubleshooting

• A channel never fires: confirm its variables are set on the server and the server was restarted. The Settings card shows a Not configured badge until the required variables are present.
• Use the test button: Settings → Alert notification channels → Send test notification delivers a sample alert to every configured channel and shows the exact per-channel error when one fails (e.g. SMTP auth, bad webhook URL).
• No deep link in the message: set PUBLIC_BASE_URL on the server.
• Server logs: a channel disabled for a bad value (malformed URL, invalid address) logs a warning at startup explaining which variable was wrong.

---

See also: Configuration · Environment template · Features · Home Assistant · Usage · Security.