From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [IPv6:2a01:7e0:0:424::9]) by lore.proxmox.com (Postfix) with ESMTPS id 74D9A1FF164 for ; Fri, 8 Nov 2024 15:42:15 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id A3F0D10269; Fri, 8 Nov 2024 15:41:43 +0100 (CET) From: Lukas Wagner To: pve-devel@lists.proxmox.com, pbs-devel@lists.proxmox.com Date: Fri, 8 Nov 2024 15:41:24 +0100 Message-Id: <20241108144124.273550-15-l.wagner@proxmox.com> X-Mailer: git-send-email 2.39.5 In-Reply-To: <20241108144124.273550-1-l.wagner@proxmox.com> References: <20241108144124.273550-1-l.wagner@proxmox.com> MIME-Version: 1.0 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.008 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record WEIRD_QUOTING 0.001 Weird repeated double-quotation marks Subject: [pve-devel] [PATCH proxmox-backup v3 14/14] docs: notification: add webhook endpoint documentation X-BeenThere: pve-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox VE development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Proxmox VE development discussion Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: pve-devel-bounces@lists.proxmox.com Sender: "pve-devel" Same information as in pve-docs but translated to restructured text. Signed-off-by: Lukas Wagner --- docs/notifications.rst | 100 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) diff --git a/docs/notifications.rst b/docs/notifications.rst index 4ba8db86..d059fa76 100644 --- a/docs/notifications.rst +++ b/docs/notifications.rst @@ -85,6 +85,106 @@ integrate with different platforms and services. See :ref:`notifications.cfg` for all configuration options. +.. _notification_targets_webhook: +Webhook +^^^^^^^ +Webhook notification targets perform HTTP requests to a configurable URL. + +The following configuration options are available: + +* ``url``: The URL to which to perform the HTTP requests. + Supports templating to inject message contents, metadata and secrets. +* ``method``: HTTP Method to use (POST/PUT/GET) +* ``header``: Array of HTTP headers that should be set for the request. + Supports templating to inject message contents, metadata and secrets. +* ``body``: HTTP body that should be sent. + Supports templating to inject message contents, metadata and secrets. +* ``secret``: Array of secret key-value pairs. These will be stored in + a protected configuration file only readable by root. Secrets can be + accessed in body/header/URL templates via the ``secrets`` namespace. +* ``comment``: Comment for this target. + +For configuration options that support templating, the +`Handlebars `_ syntax can be used to +access the following properties: + +* ``{{ title }}``: The rendered notification title +* ``{{ message }}``: The rendered notification body +* ``{{ severity }}``: The severity of the notification (``info``, ``notice``, + ``warning``, ``error``, ``unknown``) +* ``{{ timestamp }}``: The notification's timestamp as a UNIX epoch (in seconds). +* ``{{ fields. }}``: Sub-namespace for any metadata fields of the + notification. For instance, ``fields.type`` contains the notification + type - for all available fields refer to :ref:`notification_events`. +* ``{{ secrets. }}``: Sub-namespace for secrets. For instance, a secret + named ``token`` is accessible via ``secrets.token``. + +For convenience, the following helpers are available: + +* ``{{ url-encode }}``: URL-encode a property/literal. +* ``{{ escape }}``: Escape any control characters that cannot + be safely represented as a JSON string. +* ``{{ json }}``: Render a value as JSON. This can be useful + to pass a whole sub-namespace (e.g. ``fields``) as a part of a JSON payload + (e.g. ``{{ json fields }}``). + +Example - ntfy.sh +""""""""""""""""" + +* Method: ``POST`` +* URL: ``https://ntfy.sh/{{ secrets.channel }}`` +* Headers: + + * ``Markdown``: ``Yes`` +* Body:: + + ``` + {{ message }} + ``` + +* Secrets: + + * ``channel``: ```` + +Example - Discord +""""""""""""""""" + +* Method: ``POST`` +* URL: ``https://discord.com/api/webhooks/{{ secrets.token }}`` +* Headers: + + * ``Content-Type``: ``application/json`` + +* Body:: + + { + "content": "``` {{ escape message }}```" + } + +* Secrets: + + * ``token``: ```` + +Example - Slack +""""""""""""""" + +* Method: ``POST`` +* URL: ``https://hooks.slack.com/services/{{ secrets.token }}`` +* Headers: + + * ``Content-Type``: ``application/json`` + +* Body:: + + { + "text": "``` {{escape message}}```", + "type": "mrkdwn" + } + +* Secrets: + + * ``token``: ```` + .. _notification_matchers: Notification Matchers -- 2.39.5 _______________________________________________ pve-devel mailing list pve-devel@lists.proxmox.com https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel