From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) by lore.proxmox.com (Postfix) with ESMTPS id 309191FF2C6 for ; Wed, 10 Jul 2024 17:03:13 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 02F17E205; Wed, 10 Jul 2024 17:03:34 +0200 (CEST) From: Lukas Wagner To: pve-devel@lists.proxmox.com, pbs-devel@lists.proxmox.com Date: Wed, 10 Jul 2024 16:53:23 +0200 Message-Id: <20240710145324.594486-12-l.wagner@proxmox.com> X-Mailer: git-send-email 2.39.2 In-Reply-To: <20240710145324.594486-1-l.wagner@proxmox.com> References: <20240710145324.594486-1-l.wagner@proxmox.com> MIME-Version: 1.0 X-SPAM-LEVEL: Spam detection results: 0 AWL -0.495 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 HEADER_FROM_DIFFERENT_DOMAINS 0.001 From and EnvelopeFrom 2nd level mail domains are different KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment KAM_LAZY_DOMAIN_SECURITY 1 Sending domain does not have any anti-forgery methods SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_NONE 0.001 SPF: sender does not publish an SPF Record WEIRD_QUOTING 0.001 Weird repeated double-quotation marks Subject: [pve-devel] [PATCH proxmox-backup 11/12] 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.2 _______________________________________________ pve-devel mailing list pve-devel@lists.proxmox.com https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel