Introduction to Proxmox Webhook Notifications
Proxmox VE 8.3 introduces an exciting new feature to its notification system—webhook notifications. This enables users to trigger HTTP requests for events such as system updates, cluster node issues, or backup job statuses. With support for customizable headers and body content, this feature seamlessly integrates with webhook-compatible services, enhancing your automation workflows.
In this guide, we'll walk you through the Webhook notification setup process, highlighting key configuration details such as `content-type' and escaping request bodies.
Why Use Webhooks?
Webhooks provide a powerful way to automate notifications and integrate Proxmox with external services. For example:
- Notify your team on Slack or Discord about backup completion.
- Trigger an external monitoring tool like Prometheus Alertmanager or Uptime Kuma.
- Automate workflows in services like Zapier or IFTTT.
Setting Up Webhook Notifications in Proxmox VE 8.3
Step 1: Access the Notification Settings
- Log in to your Proxmox web interface.
- Navigate to Datacenter → Notifications → Notification Targets.
Step 2: Add a New Webhook Target
-
Click Add and select Webhook as the target type.
-
Fill in the following fields:
- Endpoint Name: Provide a name for the webhook (e.g.,
proxmobo). - Method/URL: Enter the HTTP method (
POST) and the webhook URL (e.g.,http://192.168.0.1:8123). - Headers: Add any required headers. For example:
Content-Type: application/json
- Body: Define the request body. Here’s an example:
{
"title": "{{ escape title }}",
"message": "{{ escape message }}"
}
- Endpoint Name: Provide a name for the webhook (e.g.,
-
Click OK to save the target.
Why Escaping is Important
Escaping is essential to ensure that special characters, such as line breaks (\n), quotation marks, and other control characters in the notification content, do not break the webhook payload format.
Step 3: Enable the Webhook in the Notification Matcher
The Notification Matcher determines which notifications are sent to your configured targets. You must enable the webhook here.
- Navigate to Datacenter → Notifications → Notification Matchers.
- Select the default-matcher or create a new matcher.
- Edit the matcher: • Go to the Targets to Notify tab. • Select your webhook target (e.g., proxmobo) along with any other desired targets.
- Click OK to save.
Step 4: Test the Webhook
- Select the newly created webhook target.
- Click Test to send a test notification.
- Verify the webhook payload in your endpoint logs.
ProxMobo’s Native Push Notification Support
As of our latest ProxMobo update, you can now receive notifications directly to your mobile device without relying solely on webhooks. This native push notification feature complements the webhook setup described above, providing a streamlined way to stay informed about critical events from anywhere.
Getting Started with Native Push Notifications in ProxMobo
-
Update ProxMobo: Ensure you’re running the latest version of ProxMobo, which includes push notification support (requires Proxmox VE >= 8.3).
-
Enable Notifications in the App: Open the ProxMobo app and navigate to navigation toolbar (ellipsis) → Notification. Turn on push notifications to authorize ProxMobo to send alerts to your device. ProxMobo will help you configure webhook and notification matcher settings in Proxmox VE.
-
Receive Alerts Instantly:
Once configured, ProxMobo will send real-time push alerts to your phone or tablet, allowing you to quickly act on important events even if you’re not actively monitoring Proxmox’s interface.
Why Consider Native Push Notifications?
• Simplicity: No need to manage additional endpoints or integrate with third-party services. • Instantaneous Updates: Receive alerts right on your device’s home screen. • Complementary to Webhooks: Use push notifications for quick status checks, and rely on webhooks for more complex automation workflows.
By incorporating native push notifications, you enrich your notification strategy. Whether you prefer the granular control of webhooks or the convenience of direct mobile alerts, ProxMobo and Proxmox VE >= 8.3 give you the flexibility to build the notification system best suited to your needs.
Tips & Tricks
Set Notification Mode to “Notification System”
When performing backups, Proxmox’s default Notification Mode is set to Auto. If you encounter issues where webhook notifications are not triggered, try setting the Notification Mode to Notification System. This ensures that the webhook-based notification system is explicitly used.
Here’s how to adjust it during a backup job:
- Go to the Backup menu for a specific container or virtual machine.
- In the Notification Mode dropdown, select Notification System.
This adjustment helps ensure notifications are routed correctly, especially if you’re testing webhook functionality.
Content-Type Header
The Content-Type header is crucial for proper webhook payload processing. Here are a few examples:
For Text-Based Payloads:
Content-Type: text/plain
Body example:
title: Backup Complete
message: The scheduled backup completed successfully.
For JSON Payloads:
Content-Type: application/json
Body example:
{
"title": "Backup Complete",
"message": "The scheduled backup completed successfully."
}
Common Use Cases • Alerting: Route backup failure notifications to a monitoring system. • Task Automation: Use webhooks to start other services or tasks after specific events. • Third-Party Integration: Easily connect Proxmox notifications with tools like Slack, Discord, or custom dashboards.
Conclusion
The new webhook notification target in Proxmox VE 8.3 opens up endless possibilities for integrating your infrastructure with external systems. Whether you’re notifying a team, triggering workflows, or logging events, the flexibility of this feature makes automation simple and powerful.