[pbs-devel] [PATCH docs 08/12] notification: add documentation for webhook target endpoints.

[Lukas Wagner]

Signed-off-by: Lukas Wagner <l.wagner at proxmox.com>
---
 notifications.adoc | 93 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 93 insertions(+)

diff --git a/notifications.adoc b/notifications.adoc
index 25a9391..b46f1d5 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.<name> }}`: 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.<name> }}`: Sub-namespace for secrets. For instance, a secret named `token`
+is accessible via `secrets.token`.
+
+For convenience, the following helpers are available:
+
+* `{{ url-encode <value/property> }}`: URL-encode a property/literal.
+* `{{ escape <value/property> }}`: Escape any control characters that cannot be
+safely represented as a JSON string.
+* `{{ json <value/property> }}`: 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`: `<your ntfy.sh channel>`
+
+===== Discord
+
+* Method: `POST`
+* URL: `https://discord.com/api/webhooks/{{ secrets.token }}`
+* Headers:
+** `Content-Type`: `application/json`
+* Body:
+----
+{
+  "content": "``` {{ escape message }}```"
+}
+----
+* Secrets:
+** `token`: `<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`: `<token>`
+
+
 [[notification_matchers]]
 Notification Matchers
 ---------------------
-- 
2.39.2