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

zerver/webhooks/zabbix/doc.md

@@ -0,0 +1,125 @@
+# Zulip Zabbix integration
+
+Receive Zabbix notifications in Zulip!
+
+!!! warn ""
+
+    **Note:** This guide is for Zabbix 5.4 and above; some older Zabbix
+    versions have a different workflow for creating an outgoing webhook.
+
+{start_tabs}
+
+1. {!create-an-incoming-webhook.md!}
+
+1. {!generate-webhook-url-basic.md!}
+
+1. Go to **Administration** in your Zabbix web interface. Click on
+   **General**, and select **Macros** from the dropdown. Click **Add**.
+
+1. Set the macro to `{$ZABBIX_URL}`. Set the value as the URL to your
+   Zabbix server, e.g., `https://zabbix.example.com`, and ensure that there
+   are no trailing slashes. Click **Update**.
+
+1. Go back to **Administration** in your Zabbix web interface. Select
+   **Media Types**, and click **Create Media Type**.
+
+1. Set **Name** to a name of your choice, such as `Zulip`. Set **Type** to
+   **Webhook**, and add the following **Parameters**:
+
+    * `hostname`: `{HOST.NAME}`
+    * `item`: `{ITEM.NAME1} is {ITEM.VALUE1}`
+    * `link`: `{$ZABBIX_URL}/tr_events.php?triggerid={TRIGGER.ID}&eventid={EVENT.ID}`
+    * `severity`: `{TRIGGER.SEVERITY}`
+    * `status`: `{TRIGGER.STATUS}`
+    * `trigger`: `{TRIGGER.NAME}`
+    * `zulip_endpoint`: the URL generated above
+
+1. Click the **Pencil** to edit the script, and replace any existing content
+   with the script below. Then, check the **Enabled** option.
+
+         try {
+            Zabbix.Log(4, 'zulip webhook script value='+value);
+
+            var result = {
+               'tags': {
+                     'endpoint': 'zulip'
+               }
+            },
+            params = JSON.parse(value),
+            req = new HttpRequest(),
+            payload = {},
+            resp;
+
+            req.addHeader('Content-Type: application/json');
+
+            payload.hostname = params.hostname;
+            payload.severity = params.severity;
+            payload.status = params.status;
+            payload.item = params.item;
+            payload.trigger = params.trigger;
+            payload.link = params.link;
+            resp = req.post(params.zulip_endpoint,
+               JSON.stringify(payload))
+
+            if (req.getStatus() != 200) {
+               throw 'Response code: '+req.getStatus();
+            }
+
+            resp = JSON.parse(resp);
+            result.tags.issue_id = resp.id;
+            result.tags.issue_key = resp.key;
+         } catch (error) {
+            Zabbix.Log(4, 'zulip issue creation failed json : '+JSON.stringify(payload));
+            Zabbix.Log(4, 'zulip issue creation failed : '+error);
+
+            result = {};
+         }
+
+         return JSON.stringify(result);
+
+1. Open **Message Templates** from the top bar. Click **Add** under **Message Type**,
+   and select **Problem**.
+
+1. Set **Subject** to `{TRIGGER.STATUS}-{TRIGGER.SEVERITY}-{TRIGGER.NAME}`.
+   Set **Message** to the following, and click **Add**:
+
+         {
+            "hostname": "{HOST.NAME}",
+            "severity": "{TRIGGER.SEVERITY}",
+            "status": "{TRIGGER.STATUS}",
+            "item": "{ITEM.NAME1} is {ITEM.VALUE1}",
+            "trigger": "{TRIGGER.NAME}",
+            "link": "{$ZABBIX_URL}/tr_events.php?triggerid={TRIGGER.ID}&eventid={EVENT.ID}"
+         }
+
+1. Go back to **Administration** in your Zabbix web interface. Click on
+   **Users**, and select the alias of the user you would like to use to
+   set the notification. Select **Media**, and click **Add**.
+
+1. Set **Type** to the name you assigned to the media type above.
+   Set **Send To** to `Zulip` or any text, as this field requires text, but
+   it isn't used. Set the severity and active periods for notifications as
+   suitable, and check the **Enabled** option. Click **Add**, and
+   select **Update**.
+
+1. Go back to your Zabbix web interface, and click **Configuration**.
+   Select **Actions**, and choose **Create Action**.
+
+1. Set **Name** to a name of your choice, such as `Zulip`. Under
+   **New Conditions**, add the conditions for triggering a notification.
+   Check the **Enabled** option, and click **Operations**.
+
+1. Under **Operations**, click **Add**, and then set **Operation Type** to
+   `Send Message`. Under **Send to Users**, choose **Add**, and select the user
+   you added the alert to above, and click **Select**. Under **Send only to**,
+   select **Zulip** or the name of your media type. Click **Add** twice.
+
+{end_tabs}
+
+{!congrats.md!}
+
+![](/static/images/integrations/zabbix/001.png)
+
+### Related documentation
+
+{!webhooks-url-specification.md!}

zerver/webhooks/zabbix/fixtures/zabbix_alert.json

@@ -0,0 +1,8 @@
+{
+    "hostname": "www.example.com",
+    "severity": "Average",
+    "status": "PROBLEM",
+    "item": "Agent ping is Up (1)",
+    "trigger": "Zabbix agent on www.example.com is unreachable for 5 minutes",
+    "link": "https://zabbix.example.com/tr_events.php?triggerid=14032&eventid=10528"
+}

zerver/webhooks/zabbix/fixtures/zabbix_invalid_payload_with_missing_data.json

@@ -0,0 +1,7 @@
+{
+    "severity": "Average",
+    "status": "PROBLEM",
+    "item": "Agent ping is Up (1)",
+    "trigger": "Zabbix agent on www.example.com is unreachable for 5 minutes",
+    "link": "https://zabbix.example.com/tr_events.php?triggerid=14032&eventid=10528"
+}

zerver/webhooks/zabbix/tests.py

@@ -0,0 +1,32 @@
+from zerver.lib.send_email import FromAddress
+from zerver.lib.test_classes import WebhookTestCase
+from zerver.models import Recipient
+from zerver.webhooks.zabbix.view import MISCONFIGURED_PAYLOAD_ERROR_MESSAGE
+
+
+class ZabbixHookTests(WebhookTestCase):
+    def test_zabbix_alert_message(self) -> None:
+        """
+        Tests if zabbix alert is handled correctly
+        """
+        expected_topic_name = "www.example.com"
+        expected_message = "PROBLEM (Average) alert on [www.example.com](https://zabbix.example.com/tr_events.php?triggerid=14032&eventid=10528):\n* Zabbix agent on www.example.com is unreachable for 5 minutes\n* Agent ping is Up (1)"
+        self.check_webhook("zabbix_alert", expected_topic_name, expected_message)
+
+    def test_zabbix_invalid_payload_with_missing_data(self) -> None:
+        """
+        Tests if invalid Zabbix payloads are handled correctly
+        """
+        self.url = self.build_webhook_url()
+        payload = self.get_body("zabbix_invalid_payload_with_missing_data")
+        result = self.client_post(self.url, payload, content_type="application/json")
+        self.assert_json_error(result, "Invalid payload")
+
+        expected_message = MISCONFIGURED_PAYLOAD_ERROR_MESSAGE.format(
+            bot_name=self.test_user.full_name,
+            support_email=FromAddress.SUPPORT,
+        ).strip()
+
+        msg = self.get_last_message()
+        self.assertEqual(msg.content, expected_message)
+        self.assertEqual(msg.recipient.type, Recipient.DIRECT_MESSAGE_GROUP)

zerver/webhooks/zabbix/view.py

@@ -0,0 +1,76 @@
+from django.core.exceptions import ValidationError
+from django.http import HttpRequest, HttpResponse
+from django.utils.translation import gettext as _
+
+from zerver.actions.message_send import send_rate_limited_pm_notification_to_bot_owner
+from zerver.decorator import webhook_view
+from zerver.lib.exceptions import JsonableError
+from zerver.lib.response import json_success
+from zerver.lib.send_email import FromAddress
+from zerver.lib.typed_endpoint import 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
+
+MISCONFIGURED_PAYLOAD_ERROR_MESSAGE = """
+Hi there! Your bot {bot_name} just received a Zabbix payload that is missing
+some data that Zulip requires. This usually indicates a configuration issue
+in your Zabbix webhook settings. Please make sure that you set the
+script correctly and provide all the required parameters
+when configuring the Zabbix webhook. Contact {support_email} if you
+need further help!
+"""
+
+ZABBIX_TOPIC_TEMPLATE = "{hostname}"
+ZABBIX_MESSAGE_TEMPLATE = """
+{status} ({severity}) alert on [{hostname}]({link}):
+* {trigger}
+* {item}
+""".strip()
+
+
+@webhook_view("Zabbix")
+@typed_endpoint
+def api_zabbix_webhook(
+    request: HttpRequest,
+    user_profile: UserProfile,
+    *,
+    payload: JsonBodyPayload[WildValue],
+) -> HttpResponse:
+    try:
+        body = get_body_for_http_request(payload)
+        topic_name = get_topic_for_http_request(payload)
+    except ValidationError:
+        message = MISCONFIGURED_PAYLOAD_ERROR_MESSAGE.format(
+            bot_name=user_profile.full_name,
+            support_email=FromAddress.SUPPORT,
+        ).strip()
+        send_rate_limited_pm_notification_to_bot_owner(user_profile, user_profile.realm, message)
+
+        raise JsonableError(_("Invalid payload"))
+
+    check_send_webhook_message(request, user_profile, topic_name, body)
+    return json_success(request)
+
+
+def get_topic_for_http_request(payload: WildValue) -> str:
+    return ZABBIX_TOPIC_TEMPLATE.format(hostname=payload["hostname"].tame(check_string))
+
+
+def get_body_for_http_request(payload: WildValue) -> str:
+    hostname = payload["hostname"].tame(check_string)
+    severity = payload["severity"].tame(check_string)
+    status = payload["status"].tame(check_string)
+    item = payload["item"].tame(check_string)
+    trigger = payload["trigger"].tame(check_string)
+    link = payload["link"].tame(check_string)
+
+    data = {
+        "hostname": hostname,
+        "severity": severity,
+        "status": status,
+        "item": item,
+        "trigger": trigger,
+        "link": link,
+    }
+    return ZABBIX_MESSAGE_TEMPLATE.format(**data)