From 7ec3f235de60fe8171acf5357ac1fe5c12810399 Mon Sep 17 00:00:00 2001
From: Lauryn Menard <lauryn@zulip.com>
Date: Sat, 29 Jun 2024 15:32:17 +0200
Subject: [PATCH] integration-docs: Update Prometheus Alertmanager for new doc
 format.

Also, revises text of `name` and `desc` URL parameters to be clearer
and note the default values that are used for the integration.

Part of #29592.
---
 zerver/webhooks/alertmanager/doc.md | 36 +++++++++++++++++++++--------
 1 file changed, 27 insertions(+), 9 deletions(-)

diff --git a/zerver/webhooks/alertmanager/doc.md b/zerver/webhooks/alertmanager/doc.md
index 3bb3e25081..0297c34541 100644
--- a/zerver/webhooks/alertmanager/doc.md
+++ b/zerver/webhooks/alertmanager/doc.md
@@ -1,25 +1,43 @@
-Get Zulip notifications from Alertmanager!
+# Zulip Prometheus Alertmanager integration
+
+Get Zulip notifications from Prometheus Alertmanager!
+
+{start_tabs}
 
 1. {!create-channel.md!}
 
 1. {!create-an-incoming-webhook.md!}
 
-1. {!generate-integration-url.md!}
-
-    Additionally, you may specify URL parameters named `name` and `desc` to specify which labels
-    or annotations will be used to construct the alert message. This allows you to use arbitrary labels
-    and annotations defined in your alerting rules.
-
-        {{ api_url }}{{ integration_url }}?api_key=abcdefgh&stream=stream%20name&name=host&desc=alertname
+1. {!generate-webhook-url-basic.md!}
 
 1. In your Alertmanager config, set up a new webhook receiver, like so:
 
     ```
     - name: ops-zulip
       webhook_configs:
-        - url: "<the URL constructed above>"
+        - url: "<the URL generated above>"
     ```
 
+{end_tabs}
+
 {!congrats.md!}
 
 ![](/static/images/integrations/alertmanager/001.png)
+
+### Configuration options
+
+- You can specify a field defined in your alerting rules (for labels
+  and/or annotations) that will be used to group alerts with the same
+  status into a single alert message in Zulip by appending a `name`
+  parameter to the generated URL, e.g., `&name=severity`. The default
+  `name` value used in the integration is `instance`.
+
+- You can specify a field defined in your alerting rules (for labels
+  and/or annotations) that will be used in the alert message text in
+  Zulip by appending a `desc` parameter to the generated URL, e.g.,
+  `&desc=description`. The default `desc` value used in the
+  integration is `alertname`.
+
+### Related documentation
+
+{!webhooks-url-specification.md!}