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

zerver/webhooks/papertrail/doc.md

@@ -0,0 +1,29 @@
+# Zulip Papertrail integration
+
+Get Zulip notifications for your Papertrail logs!
+
+{start_tabs}
+
+1. {!create-an-incoming-webhook.md!}
+
+1. {!generate-webhook-url-basic.md!}
+
+1. On your Papertrail dashboard, search for the logs you'd like to set
+   up alerts for, and click on **Save Search**.
+
+1. Provide a name for the search, and click **Save & Setup an Alert**.
+
+1. Under **Create an alert**, click on **Webhook**.
+
+1. Select options under **Alert Conditions** as appropriate. Set **URL**
+   to the URL generated above, and click **Create Alert**.
+
+{end_tabs}
+
+{!congrats.md!}
+
+![](/static/images/integrations/papertrail/001.png)
+
+### Related documentation
+
+{!webhooks-url-specification.md!}

zerver/webhooks/papertrail/fixtures/incorrect_post.json

@@ -0,0 +1,11 @@
+{
+  "saved_search": {
+    "id": 42,
+    "name": "Important stuff",
+    "query": "cron OR server1",
+    "html_edit_url": "https://papertrailapp.com/searches/42/edit",
+    "html_search_url": "https://papertrailapp.com/searches/42"
+  },
+  "max_id": 7711582041804800,
+  "min_id": 7711561783320576
+}

zerver/webhooks/papertrail/fixtures/long_post.json

@@ -0,0 +1,78 @@
+{
+  "events": [
+    {
+      "id": 7711561783320576,
+      "received_at": "2011-05-18T20:30:02-07:00",
+      "display_received_at": "May 18 20:30:02",
+      "source_ip": "208.75.57.121",
+      "source_name": "abc",
+      "source_id": 2,
+      "hostname": "abc",
+      "program": "CROND",
+      "severity": "Info",
+      "facility": "Cron",
+      "message": "message body 1"
+    },
+    {
+      "id": 7711561783320576,
+      "received_at": "2011-05-18T20:30:02-07:00",
+      "display_received_at": "May 18 20:30:02",
+      "source_ip": "208.75.57.121",
+      "source_name": "abc",
+      "source_id": 2,
+      "hostname": "abc",
+      "program": "CROND",
+      "severity": "Info",
+      "facility": "Cron",
+      "message": "message body 2"
+    },
+    {
+      "id": 7711561783320576,
+      "received_at": "2011-05-18T20:30:02-07:00",
+      "display_received_at": "May 18 20:30:02",
+      "source_ip": "208.75.57.121",
+      "source_name": "abc",
+      "source_id": 2,
+      "hostname": "abc",
+      "program": "CROND",
+      "severity": "Info",
+      "facility": "Cron",
+      "message": "message body 3"
+    },
+    {
+      "id": 7711561783320576,
+      "received_at": "2011-05-18T20:30:02-07:00",
+      "display_received_at": "May 18 20:30:02",
+      "source_ip": "208.75.57.121",
+      "source_name": "abc",
+      "source_id": 2,
+      "hostname": "abc",
+      "program": "CROND",
+      "severity": "Info",
+      "facility": "Cron",
+      "message": "message body 4"
+    },
+    {
+      "id": 7711562567655424,
+      "received_at": "2011-05-18T20:30:02-07:00",
+      "display_received_at": "May 18 20:30:02",
+      "source_ip": "208.75.57.120",
+      "source_name": "server1",
+      "source_id": 19,
+      "hostname": "def",
+      "program": "CROND",
+      "severity": "Info",
+      "facility": "Cron",
+      "message": "A short event"
+    }
+  ],
+  "saved_search": {
+    "id": 42,
+    "name": "Important stuff",
+    "query": "cron OR server1",
+    "html_edit_url": "https://papertrailapp.com/searches/42/edit",
+    "html_search_url": "https://papertrailapp.com/searches/42"
+  },
+  "max_id": 7711582041804800,
+  "min_id": 7711561783320576
+}

zerver/webhooks/papertrail/fixtures/short_post.json

@@ -0,0 +1,39 @@
+{
+  "events": [
+    {
+      "id": 7711561783320576,
+      "received_at": "2011-05-18T20:30:02-07:00",
+      "display_received_at": "May 18 20:30:02",
+      "source_ip": "208.75.57.121",
+      "source_name": "abc",
+      "source_id": 2,
+      "hostname": "abc",
+      "program": "CROND",
+      "severity": "Info",
+      "facility": "Cron",
+      "message": "message body"
+    },
+    {
+      "id": 7711562567655424,
+      "received_at": "2011-05-18T20:30:02-07:00",
+      "display_received_at": "May 18 20:30:02",
+      "source_ip": "208.75.57.120",
+      "source_name": "server1",
+      "source_id": 19,
+      "hostname": "def",
+      "program": "CROND",
+      "severity": "Info",
+      "facility": "Cron",
+      "message": "A short event"
+    }
+  ],
+  "saved_search": {
+    "id": 42,
+    "name": "Important stuff",
+    "query": "cron OR server1",
+    "html_edit_url": "https://papertrailapp.com/searches/42/edit",
+    "html_search_url": "https://papertrailapp.com/searches/42"
+  },
+  "max_id": 7711582041804800,
+  "min_id": 7711561783320576
+}

zerver/webhooks/papertrail/tests.py

@@ -0,0 +1,76 @@
+from urllib.parse import urlencode
+
+from typing_extensions import override
+
+from zerver.lib.test_classes import WebhookTestCase
+
+
+class PapertrailHookTests(WebhookTestCase):
+    def test_short_message(self) -> None:
+        expected_topic_name = "logs"
+        expected_message = """
+[Search for "Important stuff"](https://papertrailapp.com/searches/42) found **2** matches:
+
+<time:2011-05-18T20:30:02-07:00> - abc - cron OR server1:
+``` quote
+message body
+```
+<time:2011-05-18T20:30:02-07:00> - server1 - cron OR server1:
+``` quote
+A short event
+```
+""".strip()
+
+        self.check_webhook(
+            "short_post",
+            expected_topic_name,
+            expected_message,
+            content_type="application/x-www-form-urlencoded",
+        )
+
+    def test_long_message(self) -> None:
+        expected_topic = "logs"
+        expected_message = """
+[Search for "Important stuff"](https://papertrailapp.com/searches/42) found **5** matches:
+
+<time:2011-05-18T20:30:02-07:00> - abc - cron OR server1:
+``` quote
+message body 1
+```
+<time:2011-05-18T20:30:02-07:00> - abc - cron OR server1:
+``` quote
+message body 2
+```
+<time:2011-05-18T20:30:02-07:00> - abc - cron OR server1:
+``` quote
+message body 3
+```
+<time:2011-05-18T20:30:02-07:00> - abc - cron OR server1:
+``` quote
+message body 4
+```
+[See more](https://papertrailapp.com/searches/42)
+""".strip()
+
+        self.check_webhook(
+            "long_post",
+            expected_topic,
+            expected_message,
+            content_type="application/x-www-form-urlencoded",
+        )
+
+    def test_incorrect_message(self) -> None:
+        with self.assertRaises(AssertionError) as e:
+            self.check_webhook(
+                "incorrect_post", "", "", content_type="application/x-www-form-urlencoded"
+            )
+
+        self.assertIn("Events key is missing from payload", e.exception.args[0])
+
+    @override
+    def get_body(self, fixture_name: str) -> str:
+        # Papertrail webhook sends a POST request with payload parameter
+        # containing the JSON body. Documented here:
+        # https://help.papertrailapp.com/kb/how-it-works/web-hooks#encoding
+        body = self.webhook_fixture_data("papertrail", fixture_name, file_type="json")
+        return urlencode({"payload": body})

zerver/webhooks/papertrail/view.py

@@ -0,0 +1,67 @@
+from datetime import datetime
+
+from django.http import HttpRequest, HttpResponse
+from django.utils.translation import gettext as _
+from pydantic import Json
+
+from zerver.decorator import webhook_view
+from zerver.lib.exceptions import JsonableError
+from zerver.lib.response import json_success
+from zerver.lib.timestamp import datetime_to_global_time
+from zerver.lib.typed_endpoint import 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
+
+MATCHES_TEMPLATE = '[Search for "{name}"]({url}) found **{number}** matches:\n'
+SEARCH_TEMPLATE = """
+{timestamp} - {source} - {query}:
+``` quote
+{message}
+```
+""".strip()
+
+
+@webhook_view("Papertrail")
+@typed_endpoint
+def api_papertrail_webhook(
+    request: HttpRequest,
+    user_profile: UserProfile,
+    *,
+    payload: Json[WildValue],
+) -> HttpResponse:
+    if "events" not in payload:
+        raise JsonableError(_("Events key is missing from payload"))
+
+    matches = MATCHES_TEMPLATE.format(
+        name=payload["saved_search"]["name"].tame(check_string),
+        url=payload["saved_search"]["html_search_url"].tame(check_string),
+        number=str(len(payload["events"])),
+    )
+    message = [matches]
+
+    for i, event in enumerate(payload["events"]):
+        event_text = SEARCH_TEMPLATE.format(
+            timestamp=datetime_to_global_time(
+                datetime.fromisoformat(event["received_at"].tame(check_string))
+            ),
+            source=event["source_name"].tame(check_string),
+            query=payload["saved_search"]["query"].tame(check_string),
+            message=event["message"].tame(check_string),
+        )
+
+        message.append(event_text)
+
+        if i >= 3:
+            message.append(
+                "[See more]({})".format(
+                    payload["saved_search"]["html_search_url"].tame(check_string)
+                )
+            )
+            break
+
+    post = "\n".join(message)
+    topic_name = "logs"
+
+    check_send_webhook_message(request, user_profile, topic_name, post)
+    return json_success(request)