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 123BE1FF164 for ; Fri, 8 Nov 2024 15:41:55 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id CA75510181; Fri, 8 Nov 2024 15:41:38 +0100 (CET) From: Lukas Wagner To: pve-devel@lists.proxmox.com, pbs-devel@lists.proxmox.com Date: Fri, 8 Nov 2024 15:41:20 +0100 Message-Id: <20241108144124.273550-11-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.009 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 Subject: [pbs-devel] [PATCH docs v3 10/14] notification: add documentation for webhook target endpoints. X-BeenThere: pbs-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox Backup Server development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Proxmox Backup Server development discussion Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: pbs-devel-bounces@lists.proxmox.com Sender: "pbs-devel" Signed-off-by: Lukas Wagner --- notifications.adoc | 93 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) diff --git a/notifications.adoc b/notifications.adoc index 2459095..b7470fe 100644 --- a/notifications.adoc +++ b/notifications.adoc @@ -178,6 +178,99 @@ gotify: example token somesecrettoken ---- +[[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 +https://handlebarsjs.com/[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 xref:notification_events[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 }}`). + +==== Examples + +===== `ntfy.sh` + +* Method: `POST` +* URL: `https://ntfy.sh/{{ secrets.channel }}` +* Headers: +** `Markdown`: `Yes` +* Body: +---- +``` +{{ message }} +``` +---- +* Secrets: +** `channel`: `` + +===== Discord + +* Method: `POST` +* URL: `https://discord.com/api/webhooks/{{ secrets.token }}` +* Headers: +** `Content-Type`: `application/json` +* Body: +---- +{ + "content": "``` {{ escape message }}```" +} +---- +* Secrets: +** `token`: `` + +===== 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 _______________________________________________ pbs-devel mailing list pbs-devel@lists.proxmox.com https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel