Configure Proxmox Notifications for Email and Webhooks

Proxmox VE 8.1 introduced a proper centralized notification framework — SMTP endpoints, webhook targets, and matcher-based routing all managed from one config file or the web UI. This guide walks you through setting up email alerts and HTTP webhooks so backup failures, HA events, and storage errors reach you the moment they happen, whether that's your inbox, Slack, or an ntfy topic on your phone.

Key Takeaways

• Requires PVE 8.1+: The notification framework was introduced in Proxmox VE 8.1; earlier versions only support per-job email fields.
• Two endpoint types: SMTP for email and webhook for any HTTP POST target (ntfy, Gotify, Slack, Telegram).
• Matchers control routing: Filter by event type and severity — silence info noise and only page for actual errors.
• Cluster-aware: The config in /etc/pve/notifications.cfg replicates to all nodes automatically.
• Always test first: Fire a test notification before trusting backup alerts to actually land.

How the Proxmox VE 8.1 Notification Framework Works

Before 8.1, notification setup meant copying an email address into every backup job and hoping sendmail worked. The new framework flips this: you define named endpoints (where to send) and matchers (what triggers a send), then the system routes events automatically.

Everything lives in /etc/pve/notifications.cfg on the Proxmox cluster filesystem. In a cluster, it replicates to all nodes the same way VM configs do. A skeleton config looks like this:

smtp: my-smtp
    server mail.example.com
    port 587
    mode starttls
    username alerts@example.com
    from-address alerts@example.com
    mailto admin@yourdomain.com

matcher: default-matcher
    target my-smtp

The framework ships with a built-in mail-to-root endpoint that uses the local sendmail binary. In most homelabs, Postfix isn't configured as an SMTP relay on the Proxmox host, so that target silently fails. The fix is replacing the default matcher's target with an explicit SMTP endpoint you control.

Setting Up an SMTP Endpoint

Configure SMTP either in the web UI at Datacenter → Notifications → Add → SMTP Endpoint, or via pvesh:

pvesh create /cluster/notifications/endpoints/smtp \
  --name my-smtp \
  --server smtp.fastmail.com \
  --port 465 \
  --mode tls \
  --username me@fastmail.com \
  --password 'yourpassword' \
  --from-address proxmox@fastmail.com \
  --mailto admin@yourdomain.com

For Gmail, use smtp.gmail.com, port 587, starttls mode, and an App Password — Google has blocked regular credentials for SMTP since 2022, so your account password will not work here.

TLS Mode Reference

Mode	Port	Use When
starttls	587	Standard submission; negotiates TLS after connect
tls	465	SMTPS; TLS from the first byte
insecure	25	Local relay only — never send credentials this way

The --mailto-user flag accepts a Proxmox user ID such as root@pam and resolves the email address from that user's profile under Datacenter → Permissions → Users. The --mailto flag takes a raw email address directly. To notify multiple recipients, repeat the flag:

pvesh create /cluster/notifications/endpoints/smtp \
  --name team-smtp \
  --server smtp.example.com \
  --port 587 \
  --mode starttls \
  --username alerts@example.com \
  --password 'yourpassword' \
  --from-address proxmox@example.com \
  --mailto ops@company.com \
  --mailto oncall@company.com

If you run Proxmox Backup Server alongside Proxmox VE, PBS has its own notification framework configured separately in the PBS web UI. The concepts are identical but the config is a separate service — see Automated Backups with Proxmox Backup Server for the full PBS workflow including retention and offsite replication.

Testing the SMTP Endpoint

Fire a test message before trusting this for production backup alerts:

pvesh create /cluster/notifications/endpoints/smtp/my-smtp/test

Expect the email within 60 seconds. If nothing arrives, check the log:

journalctl -u postfix --since "5 minutes ago"

The most common failure causes:

• Port 25 blocked outbound by your ISP or upstream router — use 587 or 465 instead
• Wrong app password — Gmail and Fastmail require a dedicated SMTP app password, not your account password
• TLS mode mismatch — flip between starttls and tls if you see TLS handshake errors in the log
• Firewall blocking outbound SMTP — if you run strict egress rules on the Proxmox host, you'll need to allow TCP 465 or 587 outbound; the Hardening Proxmox VE: Firewall, fail2ban, and SSH Security guide covers how those egress rules are structured

Adding a Webhook Endpoint

Webhook endpoints send an HTTP POST to any URL — ntfy, Gotify, Slack, Telegram bots, Mattermost, or a custom receiver. The webhook endpoint type has been available since Proxmox VE 8.1.

For ntfy (a lightweight push notification server that runs cleanly in an LXC container):

pvesh create /cluster/notifications/endpoints/webhook \
  --name ntfy-homelab \
  --url 'https://ntfy.example.com/proxmox-alerts' \
  --method POST \
  --header 'Authorization:Bearer your-ntfy-token' \
  --body '{"title":"{{title}}","message":"{{message}}"}'

For Slack via an incoming webhook URL:

pvesh create /cluster/notifications/endpoints/webhook \
  --name slack-ops \
  --url 'https://hooks.slack.com/services/T00000000/B00000000/XXXX' \
  --method POST \
  --body '{"text":"*{{title}}*\n{{message}}"}'

The body field supports Handlebars-style template variables:

• {{title}} — short event subject
• {{message}} — full event body
• {{severity}} — one of info, notice, warning, or error
• {{timestamp}} — Unix epoch seconds

Configuring Matchers to Route Alerts

A matcher without filters is a catch-all — it sends every event to its target:

pvesh create /cluster/notifications/matchers \
  --name catch-all \
  --target my-smtp

Add --filter-severity to cut down on noise. This matcher sends only errors and warnings to the webhook:

pvesh create /cluster/notifications/matchers \
  --name critical-to-ntfy \
  --target ntfy-homelab \
  --filter-severity '["error","warning"]'

Filter by event type with --filter-type to catch only backup job results:

pvesh create /cluster/notifications/matchers \
  --name backup-alerts \
  --target my-smtp \
  --filter-type '["vzdump"]' \
  --filter-severity '["error","warning"]'

Multiple matchers are independent — an error event can match both a filter-severity error webhook matcher and a catch-all email matcher, and both will fire. There is no stop-processing rule.

What Events Actually Generate Notifications

This catches people off guard: the notification framework only fires for system-initiated events, not manual UI actions.

Event Type	What Triggers It	Severity
vzdump	Backup job finishes (success, fail, or warning)	info / error / warning
replication	Storage replication job completes or fails	info or error
package-updates	Weekly update scan finds available packages	notice
fencing	HA manager fences a node	error
cluster	Node join/leave or quorum change	warning or error

Manual operations — cloning a VM, live migration, snapshot creation, moving a disk between pools — do not generate notifications. Expecting a ping when you hand-migrate a VM and getting silence is the most common "is this broken?" moment for new users. It's not broken.

A Complete Working Config

Here is the exact /etc/pve/notifications.cfg running on a three-node Proxmox VE 9.1 cluster. Email gets everything; ntfy only gets errors, so my phone buzzes for actual problems and not for 50 successful nightly backup completions:

smtp: fastmail
    server smtp.fastmail.com
    port 465
    mode tls
    username me@fastmail.com
    from-address proxmox@fastmail.com
    mailto me@fastmail.com
    comment Email catch-all

webhook: ntfy
    url https://ntfy.sh/my-private-topic-xxxxxx
    method POST
    header Authorization:Bearer ntfy-token-here
    body {"title":"{{title}}","message":"{{message}}"}
    comment Phone push for errors only

matcher: errors-to-phone
    target ntfy
    filter-severity error

matcher: everything-to-email
    target fastmail
    comment Catch-all

Edit this file directly for bulk changes. No service restart is needed — Proxmox reads it on demand. The file is plain text, and version-controlling it alongside your other infrastructure configs is straightforward.

What About the Default mail-to-root Target?

Proxmox ships with a built-in mail-to-root SMTP endpoint and a default-matcher that points to it. If sendmail isn't configured on your Proxmox host — which is true for most homelab installations — this silently fails. Go to Datacenter → Notifications, edit the default-matcher, and point it to your named SMTP endpoint instead.

Migrating from Per-Job Email to Matchers

If you set email addresses directly on vzdump jobs before Proxmox VE 8.1, those inline fields still work for backward compatibility. But to get matcher routing and webhooks, you need to clear them. Check what you have first:

grep -r "mailto" /etc/pve/jobs.cfg

For each job with an inline mailto, clear the field under Datacenter → Backup → Edit. For a large number of jobs, edit /etc/pve/jobs.cfg directly to strip mailto lines, then verify none remain:

pvesh get /cluster/jobs/vzdump

Confirm no returned jobs carry a mailto field before relying on matchers alone.

Conclusion

With a named SMTP endpoint and a couple of matchers in /etc/pve/notifications.cfg, Proxmox VE 9.1 reliably delivers backup failures, HA fencing events, and replication errors to your inbox or phone — no per-job configuration needed. The twenty-minute setup pays off the first time a 3 AM backup failure lands in your inbox before your users notice. The logical refinement from here: add filter-severity error to your webhook matcher so only genuine failures wake you up, and let the daily info-level noise stay in email. If you haven't scheduled automated backup jobs yet, Automated Backups with Proxmox Backup Server covers everything from retention policies to off-site replication.