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

zerver/webhooks/updown/doc.md

@@ -0,0 +1,25 @@
+# Zulip Updown integration
+
+See Updown reports in Zulip!
+
+{start_tabs}
+
+1. {!create-an-incoming-webhook.md!}
+
+1. {!generate-webhook-url-basic.md!}
+
+1. On [your Updown settings page](https://updown.io/settings/edit), go to **Webhooks**.
+
+1. Add the URL generated above to the list of **Webhook endpoint URLs**.
+
+{end_tabs}
+
+{!congrats.md!}
+
+![](/static/images/integrations/updown/001.png)
+
+{!event-filtering-additional-feature.md!}
+
+### Related documentation
+
+{!webhooks-url-specification.md!}

zerver/webhooks/updown/fixtures/check_down_one_event.json

@@ -0,0 +1,27 @@
+[{
+  "event": "check.down",
+  "check": {
+    "token": "ngg8",
+    "url": "https://updown.io",
+    "alias": "",
+    "last_status": 500,
+    "uptime": 100.0,
+    "down": true,
+    "down_since": "2016-02-07T13:11:43Z",
+    "error": "500",
+    "period": 30,
+    "apdex_t": 0.25,
+    "string_match": "",
+    "enabled": true,
+    "published": true,
+    "last_check_at": "2016-02-07T13:12:13Z",
+    "next_check_at": "2016-02-07T13:12:43Z",
+    "favicon_url": "https://updown.io/favicon.png"
+  },
+  "downtime": {
+    "error": "500",
+    "started_at": "2016-02-07T13:11:43Z",
+    "ended_at": null,
+    "duration": null
+  }
+}]

zerver/webhooks/updown/fixtures/check_multiple_events.json

@@ -0,0 +1,56 @@
+[
+  {
+    "event": "check.down",
+    "check": {
+      "token": "ngg8",
+      "url": "https://updown.io",
+      "alias": "",
+      "last_status": 200,
+      "uptime": 99.954,
+      "down": false,
+      "down_since": null,
+      "error": null,
+      "period": 30,
+      "apdex_t": 0.25,
+      "string_match": "",
+      "enabled": true,
+      "published": true,
+      "last_check_at": "2016-02-07T13:16:07Z",
+      "next_check_at": "2016-02-07T13:16:37Z",
+      "favicon_url": "https://updown.io/favicon.png"
+    },
+    "downtime": {
+      "error": "500",
+      "started_at": "2016-02-07T13:11:43Z",
+      "ended_at": null,
+      "duration": null
+    }
+  },
+  {
+    "event": "check.up",
+    "check": {
+      "token": "ngg8",
+      "url": "https://updown.io",
+      "alias": "",
+      "last_status": 200,
+      "uptime": 99.954,
+      "down": false,
+      "down_since": null,
+      "error": null,
+      "period": 30,
+      "apdex_t": 0.25,
+      "string_match": "",
+      "enabled": true,
+      "published": true,
+      "last_check_at": "2016-02-07T13:16:07Z",
+      "next_check_at": "2016-02-07T13:16:37Z",
+      "favicon_url": "https://updown2.io/favicon.png"
+    },
+    "downtime": {
+      "error": "500",
+      "started_at": "2016-02-07T13:11:43Z",
+      "ended_at": "2016-02-07T13:11:44Z",
+      "duration": 1
+    }
+  }
+]

zerver/webhooks/updown/fixtures/check_up_again_one_event.json

@@ -0,0 +1,27 @@
+[{
+  "event": "check.up",
+  "check": {
+    "token": "ngg8",
+    "url": "https://updown.io",
+    "alias": "",
+    "last_status": 200,
+    "uptime": 99.954,
+    "down": false,
+    "down_since": null,
+    "error": null,
+    "period": 30,
+    "apdex_t": 0.25,
+    "string_match": "",
+    "enabled": true,
+    "published": true,
+    "last_check_at": "2016-02-07T13:16:07Z",
+    "next_check_at": "2016-02-07T13:16:37Z",
+    "favicon_url": "https://updown.io/favicon.png"
+  },
+  "downtime": {
+    "error": "500",
+    "started_at": "2016-02-07T13:11:43Z",
+    "ended_at": "2016-02-07T13:16:07Z",
+    "duration": 265
+  }
+}]

zerver/webhooks/updown/fixtures/check_up_first_time.json

@@ -0,0 +1,27 @@
+[{
+  "event": "check.up",
+  "check": {
+    "token": "ngg8",
+    "url": "https://updown.io",
+    "alias": "",
+    "last_status": 200,
+    "uptime": 99.954,
+    "down": false,
+    "down_since": null,
+    "error": null,
+    "period": 30,
+    "apdex_t": 0.25,
+    "string_match": "",
+    "enabled": true,
+    "published": true,
+    "last_check_at": "2016-02-07T13:16:07Z",
+    "next_check_at": "2016-02-07T13:16:37Z",
+    "favicon_url": "https://updown.io/favicon.png"
+  },
+  "downtime": {
+    "error": null,
+    "started_at": null,
+    "ended_at": null,
+    "duration": null
+  }
+}]

zerver/webhooks/updown/fixtures/unknown_event.json

@@ -0,0 +1,27 @@
+[{
+  "event": "unknown",
+  "check": {
+    "token": "ngg8",
+    "url": "https://updown.io",
+    "alias": "",
+    "last_status": 200,
+    "uptime": 99.954,
+    "down": false,
+    "down_since": null,
+    "error": null,
+    "period": 30,
+    "apdex_t": 0.25,
+    "string_match": "",
+    "enabled": true,
+    "published": true,
+    "last_check_at": "2016-02-07T13:16:07Z",
+    "next_check_at": "2016-02-07T13:16:37Z",
+    "favicon_url": "https://updown.io/favicon.png"
+  },
+  "downtime": {
+    "error": null,
+    "started_at": null,
+    "ended_at": null,
+    "duration": null
+  }
+}]

zerver/webhooks/updown/tests.py

@@ -0,0 +1,57 @@
+from zerver.lib.test_classes import WebhookTestCase
+
+
+class UpdownHookTests(WebhookTestCase):
+    def test_updown_check_down_event(self) -> None:
+        expected_topic_name = "https://updown.io"
+        expected_message = (
+            "Service is `down`. It returned a 500 error at <time:2016-02-07T13:11:43+00:00>."
+        )
+        self.check_webhook("check_down_one_event", expected_topic_name, expected_message)
+
+    def test_updown_check_up_again_event(self) -> None:
+        expected_topic_name = "https://updown.io"
+        expected_message = "Service is `up` again after 4 minutes 25 seconds."
+        self.check_webhook("check_up_again_one_event", expected_topic_name, expected_message)
+
+    def test_updown_check_up_event(self) -> None:
+        expected_topic_name = "https://updown.io"
+        expected_message = "Service is `up`."
+        self.check_webhook("check_up_first_time", expected_topic_name, expected_message)
+
+    def test_updown_check_up_multiple_events(self) -> None:
+        topic_name = "https://updown.io"
+
+        down_content = (
+            "Service is `down`. It returned a 500 error at <time:2016-02-07T13:11:43+00:00>."
+        )
+        up_content = "Service is `up` again after 1 second."
+
+        self.subscribe(self.test_user, self.channel_name)
+        payload = self.get_body("check_multiple_events")
+
+        msg = self.send_webhook_payload(
+            self.test_user,
+            self.url,
+            payload,
+            content_type="application/json",
+        )
+
+        msg = self.get_second_to_last_message()
+        self.assert_channel_message(
+            message=msg,
+            channel_name=self.channel_name,
+            topic_name=topic_name,
+            content=down_content,
+        )
+
+        msg = self.get_last_message()
+        self.assert_channel_message(
+            message=msg,
+            channel_name=self.channel_name,
+            topic_name=topic_name,
+            content=up_content,
+        )
+
+    def test_unknown_event(self) -> None:
+        self.check_webhook("unknown_event", expect_noop=True)

zerver/webhooks/updown/view.py

@@ -0,0 +1,99 @@
+# Webhooks for external integrations.
+import re
+from datetime import datetime
+
+from django.http import HttpRequest, HttpResponse
+
+from zerver.decorator import webhook_view
+from zerver.lib.exceptions import UnsupportedWebhookEventTypeError
+from zerver.lib.response import json_success
+from zerver.lib.timestamp import datetime_to_global_time
+from zerver.lib.typed_endpoint import JsonBodyPayload, typed_endpoint
+from zerver.lib.validator import WildValue, check_int, check_none_or, check_string
+from zerver.lib.webhooks.common import check_send_webhook_message
+from zerver.models import UserProfile
+
+TOPIC_TEMPLATE = "{service_url}"
+
+
+def send_message_for_event(
+    request: HttpRequest, user_profile: UserProfile, event: WildValue
+) -> None:
+    event_type = get_event_type(event)
+    topic_name = TOPIC_TEMPLATE.format(service_url=event["check"]["url"].tame(check_string))
+    body = EVENT_TYPE_BODY_MAPPER[event_type](event)
+    check_send_webhook_message(request, user_profile, topic_name, body, event_type)
+
+
+def get_body_for_up_event(event: WildValue) -> str:
+    body = "Service is `up`"
+    event_downtime = event["downtime"]
+    if event_downtime["started_at"].tame(check_none_or(check_string)):
+        body = f"{body} again"
+        duration = event_downtime["duration"].tame(check_none_or(check_int))
+        if duration:
+            string_date = get_time_string_based_on_duration(duration)
+            if string_date:
+                body = f"{body} after {string_date}"
+    return f"{body}."
+
+
+def get_time_string_based_on_duration(duration: int) -> str:
+    days, reminder = divmod(duration, 86400)
+    hours, reminder = divmod(reminder, 3600)
+    minutes, seconds = divmod(reminder, 60)
+
+    string_date = ""
+    string_date += add_time_part_to_string_date_if_needed(days, "day")
+    string_date += add_time_part_to_string_date_if_needed(hours, "hour")
+    string_date += add_time_part_to_string_date_if_needed(minutes, "minute")
+    string_date += add_time_part_to_string_date_if_needed(seconds, "second")
+    return string_date.rstrip()
+
+
+def add_time_part_to_string_date_if_needed(value: int, text_name: str) -> str:
+    if value == 1:
+        return f"1 {text_name} "
+    if value > 1:
+        return f"{value} {text_name}s "
+    return ""
+
+
+def get_body_for_down_event(event: WildValue) -> str:
+    started_at = event["downtime"]["started_at"].tame(check_string)
+    dt = datetime.fromisoformat(started_at)
+    pretty_started_at = datetime_to_global_time(dt)
+    return "Service is `down`. It returned a {} error at {}.".format(
+        event["downtime"]["error"].tame(check_none_or(check_string)),
+        # started_at is not None in a "down" event.
+        pretty_started_at,
+    )
+
+
+EVENT_TYPE_BODY_MAPPER = {
+    "up": get_body_for_up_event,
+    "down": get_body_for_down_event,
+}
+ALL_EVENT_TYPES = list(EVENT_TYPE_BODY_MAPPER.keys())
+
+
+@webhook_view("Updown", all_event_types=ALL_EVENT_TYPES)
+@typed_endpoint
+def api_updown_webhook(
+    request: HttpRequest,
+    user_profile: UserProfile,
+    *,
+    payload: JsonBodyPayload[WildValue],
+) -> HttpResponse:
+    for event in payload:
+        send_message_for_event(request, user_profile, event)
+    return json_success(request)
+
+
+def get_event_type(event: WildValue) -> str:
+    event_type_match = re.match(r"check.(.*)", event["event"].tame(check_string))
+    if event_type_match:
+        event_type = event_type_match.group(1)
+        if event_type in EVENT_TYPE_BODY_MAPPER:
+            return event_type
+    raise UnsupportedWebhookEventTypeError(event["event"].tame(check_string))