snapshot of https://github.com/zulip/zulip.git @ 48c69911c7dd4e03b20552eb3bd77ad8151c1357 (2026-09-15)

zerver/webhooks/alertmanager/doc.md

@@ -0,0 +1,41 @@
+# Zulip Prometheus Alertmanager integration
+
+Get Zulip notifications from Prometheus Alertmanager!
+
+{start_tabs}
+
+1. {!create-an-incoming-webhook.md!}
+
+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 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!}

zerver/webhooks/alertmanager/fixtures/alert.json

@@ -0,0 +1,51 @@
+{
+    "receiver": "ops-zulip",
+    "status": "firing",
+    "groupLabels": {},
+    "commonLabels": {
+        "alertname": "High CPU Temperature",
+        "severity": "critical"
+    },
+    "commonAnnotations": {
+        "summary": "High CPU core temperature"
+    },
+    "externalURL": "http://ops1:9093",
+    "version": "4",
+    "groupKey": "{}/{}:{}",
+    "alerts": [
+        {
+            "status": "firing",
+            "labels": {
+                "alertname": "High CPU Temperature",
+                "host": "andromeda",
+                "severity": "critical"
+            },
+            "annotations": {
+                "description": "CPU core temperature is 34.75C",
+                "topic": "andromeda",
+                "summary": "High CPU core temperature"
+            },
+            "startsAt": "2020-02-06T00:17:58.432911368Z",
+            "endsAt": "0001-01-01T00:00:00Z",
+            "generatorURL": "http://cobalt:9090/graph?g0.expr=avg+by%28host%29+%28sensors_temp_input%7Bfeature%3D~%22core_%5B0-9%5D%2B%22%7D%29+%3E+15&g0.tab=1",
+            "fingerprint": "a1bc48475b20e73d"
+        },
+        {
+            "status": "firing",
+            "labels": {
+                "alertname": "High CPU Temperature",
+                "host": "andromeda",
+                "severity": "critical"
+            },
+            "annotations": {
+                "description": "CPU core temperature is 17.625C",
+                "topic": "andromeda",
+                "summary": "High CPU core temperature"
+            },
+            "startsAt": "2020-02-06T00:17:58.432911368Z",
+            "endsAt": "0001-01-01T00:00:00Z",
+            "generatorURL": "http://cobalt:9090/graph?g0.expr=avg+by%28host%29+%28sensors_temp_input%7Bfeature%3D~%22core_%5B0-9%5D%2B%22%7D%29+%3E+15&g0.tab=1",
+            "fingerprint": "c2ea85182f28cbd9"
+        }
+    ]
+}

zerver/webhooks/alertmanager/fixtures/single_alert.json

@@ -0,0 +1,34 @@
+{
+    "receiver": "ops-zulip",
+    "status": "resolved",
+    "groupLabels": {},
+    "commonLabels": {
+        "alertname": "High CPU Temperature",
+        "severity": "critical"
+    },
+    "commonAnnotations": {
+        "summary": "High CPU core temperature"
+    },
+    "externalURL": "http://ops1:9093",
+    "version": "4",
+    "groupKey": "{}/{}:{}",
+    "alerts": [
+        {
+            "status": "resolved",
+            "labels": {
+                "alertname": "High CPU Temperature",
+                "host": "andromeda",
+                "severity": "critical"
+            },
+            "annotations": {
+                "description": "CPU core temperature is 34.75C",
+                "topic": "andromeda",
+                "summary": "High CPU core temperature"
+            },
+            "startsAt": "2020-02-06T00:17:58.432911368Z",
+            "endsAt": "0001-01-01T00:00:00Z",
+            "generatorURL": "http://cobalt:9090/graph?g0.expr=avg+by%28host%29+%28sensors_temp_input%7Bfeature%3D~%22core_%5B0-9%5D%2B%22%7D%29+%3E+15&g0.tab=1",
+            "fingerprint": "a1bc48475b20e73d"
+        }
+    ]
+}

zerver/webhooks/alertmanager/fixtures/single_alert_no_url.json

@@ -0,0 +1,33 @@
+{
+    "receiver": "ops-zulip",
+    "status": "firing",
+    "groupLabels": {},
+    "commonLabels": {
+        "alertname": "High CPU Temperature",
+        "severity": "critical"
+    },
+    "commonAnnotations": {
+        "summary": "High CPU core temperature"
+    },
+    "externalURL": "http://ops1:9093",
+    "version": "4",
+    "groupKey": "{}/{}:{}",
+    "alerts": [
+        {
+            "status": "firing",
+            "labels": {
+                "alertname": "High CPU Temperature",
+                "host": "andromeda",
+                "severity": "critical"
+            },
+            "annotations": {
+                "description": "CPU core temperature is 34.75C",
+                "topic": "andromeda",
+                "summary": "High CPU core temperature"
+            },
+            "startsAt": "2020-02-06T00:17:58.432911368Z",
+            "endsAt": "0001-01-01T00:00:00Z",
+            "fingerprint": "a1bc48475b20e73d"
+        }
+    ]
+}

zerver/webhooks/alertmanager/tests.py

@@ -0,0 +1,44 @@
+from zerver.lib.test_classes import WebhookTestCase
+
+
+class AlertmanagerHookTests(WebhookTestCase):
+    URL_TEMPLATE = "/api/v1/external/alertmanager?&api_key={api_key}&stream={stream}&name=topic&desc=description"
+
+    def test_error_issue_message(self) -> None:
+        expected_topic_name = "andromeda"
+        expected_message = """
+:alert: **FIRING**
+* CPU core temperature is 34.75C ([source](http://cobalt:9090/graph?g0.expr=avg+by%28host%29+%28sensors_temp_input%7Bfeature%3D~%22core_%5B0-9%5D%2B%22%7D%29+%3E+15&g0.tab=0))
+* CPU core temperature is 17.625C ([source](http://cobalt:9090/graph?g0.expr=avg+by%28host%29+%28sensors_temp_input%7Bfeature%3D~%22core_%5B0-9%5D%2B%22%7D%29+%3E+15&g0.tab=0))
+""".strip()
+
+        self.check_webhook(
+            "alert",
+            expected_topic_name,
+            expected_message,
+            "application/json",
+        )
+
+    def test_single_error_issue_message(self) -> None:
+        expected_topic_name = "andromeda"
+        expected_message = """
+:squared_ok: **Resolved** CPU core temperature is 34.75C ([source](http://cobalt:9090/graph?g0.expr=avg+by%28host%29+%28sensors_temp_input%7Bfeature%3D~%22core_%5B0-9%5D%2B%22%7D%29+%3E+15&g0.tab=0))
+""".strip()
+
+        self.check_webhook(
+            "single_alert",
+            expected_topic_name,
+            expected_message,
+            "application/json",
+        )
+
+    def test_single_alert_no_generator_url(self) -> None:
+        expected_topic_name = "andromeda"
+        expected_message = ":alert: **FIRING** CPU core temperature is 34.75C"
+
+        self.check_webhook(
+            "single_alert_no_url",
+            expected_topic_name,
+            expected_message,
+            "application/json",
+        )

zerver/webhooks/alertmanager/view.py

@@ -0,0 +1,65 @@
+# Webhooks for external integrations.
+
+from typing import Annotated
+
+from django.http import HttpRequest, HttpResponse
+
+from zerver.decorator import webhook_view
+from zerver.lib.response import json_success
+from zerver.lib.typed_endpoint import ApiParamConfig, JsonBodyPayload, typed_endpoint
+from zerver.lib.validator import WildValue, check_string
+from zerver.lib.webhooks.common import check_send_webhook_message
+from zerver.models import UserProfile
+
+
+@webhook_view("Alertmanager")
+@typed_endpoint
+def api_alertmanager_webhook(
+    request: HttpRequest,
+    user_profile: UserProfile,
+    *,
+    payload: JsonBodyPayload[WildValue],
+    name_field: Annotated[str, ApiParamConfig("name")] = "instance",
+    desc_field: Annotated[str, ApiParamConfig("desc")] = "alertname",
+) -> HttpResponse:
+    topics: dict[str, dict[str, list[str]]] = {}
+
+    for alert in payload["alerts"]:
+        labels = alert.get("labels", {})
+        annotations = alert.get("annotations", {})
+
+        name = labels.get(name_field, annotations.get(name_field, "(unknown)")).tame(check_string)
+        desc = labels.get(
+            desc_field, annotations.get(desc_field, f"<missing field: {desc_field}>")
+        ).tame(check_string)
+
+        if "generatorURL" in alert:
+            url = alert["generatorURL"].tame(check_string).replace("tab=1", "tab=0")
+            body = f"{desc} ([source]({url}))"
+        else:
+            body = desc
+        if name not in topics:
+            topics[name] = {"firing": [], "resolved": []}
+        topics[name][alert["status"].tame(check_string)].append(body)
+
+    for topic_name, statuses in topics.items():
+        for status, messages in statuses.items():
+            if len(messages) == 0:
+                continue
+
+            if status == "firing":
+                icon = ":alert:"
+                title = "FIRING"
+            else:
+                title = "Resolved"
+                icon = ":squared_ok:"
+
+            if len(messages) == 1:
+                body = f"{icon} **{title}** {messages[0]}"
+            else:
+                message_list = "\n".join(f"* {m}" for m in messages)
+                body = f"{icon} **{title}**\n{message_list}"
+
+            check_send_webhook_message(request, user_profile, topic_name, body)
+
+    return json_success(request)