Setup Proxmox NTFY Notifications with CLI

This tip is largely a copy-paste of my README on the Proxmox setup in my homelab.

You can achieve the same setup using the Proxmox Web-UI, but I prefer to use CLI because it’s repeatable, extendable, and scalable. If I ever needed to change the NTFY setup, I just need to re-run the commands and I’m done.

Proxmox has a pretty nice API that we can access with the pvesh command. For example, the documentation for the notification endpoint is here.

Here is how to do that.

From the web-UI of your NTFY instance, click on “Subscribe to a topic”. Create some random name for the topic, that is not easily discoverable.

Go to Account tab and create a token for Proxmox.

First, read in your topic name into an environment variable TOPIC, i.e., random string after https://ntfy.example.com/.

We will need a base64 version of TOPIC for the setup.

TOPIC_BASE64=$(echo -n $TOPIC | base64)

All headers and the body of the POST request should also be in base64:

echo -n "yes" | base64
# eWVz

echo -n "{{ title }}" | base64
# e3sgdGl0bGUgfX0=

echo -n "{{ message }}" | base64
# e3sgbWVzc2FnZSB9fQ==

echo -n "{{ secrets.token }}" | base64
# e3sgc2VjcmV0cy50b2tlbiB9fQ==

I use API keys to access my ntfy instance.

On your instances create an API key for Proxmox notification.

Create a base64 version of the authorization token secret.

read -s AUTHORIZATION_TOKEN # should be 'Bearer <token>'
AUTHORIZATION_TOKEN_BASE64=$(echo -n $AUTHORIZATION_TOKEN | base64)

Next, run the command to add the notification target:

pvesh create /cluster/notifications/endpoints/webhook --name ntfy --method post \
  --url "https://ntfy.example.com/{{ secrets.topic }}" \
  --header name=Markdown,value=eWVz \
  --header name=X-Title,value=e3sgdGl0bGUgfX0= --body e3sgbWVzc2FnZSB9fQ== \
  --header name=Authorization,value=e3sgc2VjcmV0cy50b2tlbiB9fQ== \
  --secret name=topic,value=$TOPIC_BASE64 \
  --secret name=token,value=$AUTHORIZATION_TOKEN_BASE64

Substitute https://ntfy.example.com with your instance address.

Test that the notification can be received successfully:

pvesh create /cluster/notifications/targets/ntfy/test

Unset the environment variables:

unset TOPIC
unset TOPIC_BASE64
unset AUTHORIZATION_TOKEN
unset AUTHORIZATION_TOKEN_BASE64

Notification Matchers Link to heading

Create notification matchers. Here I set the target to ntfy.

pvesh set /cluster/notifications/matchers/default-matcher --disable true

pvesh create /cluster/notifications/matchers --name errors \
  --match-severity unknown,warning,error --target ntfy \
  --comment "Notify about unknown, warnings or errors"