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

zerver/webhooks/canarytoken/doc.md

@@ -0,0 +1,32 @@
+# Zulip Thinkst Canarytoken integration
+
+See your Thinkst Canarytoken alerts in Zulip!
+
+This integration works with Canarytokens from
+[canarytokens.org][canarytokens], not Thinkst's paid product. See the
+[Zulip Thinkst integration](/integrations/thinkst) for those!
+
+{start_tabs}
+
+1. {!create-an-incoming-webhook.md!}
+
+1. {!generate-webhook-url-basic.md!}
+
+1. Go to [canarytokens.org][canarytokens].
+
+1. From the **Select your token**  dropdown, choose the type of webhook
+   that you want to create. In the **Provide an email address or webhook
+   URL** field, enter the generated URL above. Add a reminder note, and
+   click **Create my Canarytoken**.
+
+{end_tabs}
+
+{!congrats.md!}
+
+![](/static/images/integrations/canarytoken/001.png)
+
+### Related documentation
+
+{!webhooks-url-specification.md!}
+
+[canarytokens]: https://canarytokens.org

zerver/webhooks/canarytoken/fixtures/canarytoken_new.json

@@ -0,0 +1,12 @@
+{
+  "manage_url": "http://example.com/test/url/for/webhook",
+  "memo": "Congrats! The newly saved webhook works",
+  "additional_data": {
+    "src_ip": "1.1.1.1",
+    "useragent": "Mozilla/5.0...",
+    "referer": "http://example.com/referrer",
+    "location": "http://example.com/location"
+  },
+  "channel": "HTTP",
+  "time": "2020-06-09 14:04:39"
+}

zerver/webhooks/canarytoken/fixtures/canarytoken_real.json

@@ -0,0 +1,12 @@
+{
+  "manage_url": "https://canarytokens.org/manage?token=foo&auth=bar",
+  "memo": "Canarytoken example",
+  "additional_data": {
+    "src_ip": "81.151.13.3",
+    "useragent": "Mozilla/5.0 (X11; Linux x86_64; rv:76.0) Gecko/20100101 Firefox/76.0",
+    "referer": null,
+    "location": null
+  },
+  "channel": "HTTP",
+  "time": "2020-06-09 14:04:47 (UTC)"
+}

zerver/webhooks/canarytoken/tests.py

@@ -0,0 +1,48 @@
+from zerver.lib.test_classes import WebhookTestCase
+
+
+class CanarytokensHookTests(WebhookTestCase):
+    def test_canarytoken_new(self) -> None:
+        expected_message = (
+            "**:alert: Canarytoken has been triggered on <time:2020-06-09T14:04:39+00:00>!**\n\n"
+            "Congrats! The newly saved webhook works \n\n"
+            "[Manage this canarytoken](http://example.com/test/url/for/webhook)"
+        )
+
+        self.check_webhook(
+            "canarytoken_new",
+            "canarytoken alert",
+            expected_message,
+            content_type="application/x-www-form-urlencoded",
+        )
+
+    def test_canarytoken_real(self) -> None:
+        expected_message = (
+            "**:alert: Canarytoken has been triggered on <time:2020-06-09T14:04:47+00:00>!**\n\n"
+            "Canarytoken example \n\n"
+            "[Manage this canarytoken]"
+            "(https://canarytokens.org/manage?token=foo&auth=bar)"
+        )
+
+        self.check_webhook(
+            "canarytoken_real",
+            "canarytoken alert",
+            expected_message,
+            content_type="application/x-www-form-urlencoded",
+        )
+
+    def test_canarytoken_with_specific_topic(self) -> None:
+        self.url = self.build_webhook_url(topic="foo")
+        expected_message = (
+            "**:alert: Canarytoken has been triggered on <time:2020-06-09T14:04:47+00:00>!**\n\n"
+            "Canarytoken example \n\n"
+            "[Manage this canarytoken]"
+            "(https://canarytokens.org/manage?token=foo&auth=bar)"
+        )
+
+        self.check_webhook(
+            "canarytoken_real",
+            "foo",
+            expected_message,
+            content_type="application/x-www-form-urlencoded",
+        )

zerver/webhooks/canarytoken/view.py

@@ -0,0 +1,48 @@
+# Webhooks for external integrations.
+
+from datetime import datetime
+
+from django.http import HttpRequest, HttpResponse
+
+from zerver.decorator import webhook_view
+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_string
+from zerver.lib.webhooks.common import OptionalUserSpecifiedTopicStr, check_send_webhook_message
+from zerver.models import UserProfile
+
+
+@webhook_view("Canarytokens")
+@typed_endpoint
+def api_canarytoken_webhook(
+    request: HttpRequest,
+    user_profile: UserProfile,
+    *,
+    message: JsonBodyPayload[WildValue],
+    user_specified_topic: OptionalUserSpecifiedTopicStr = None,
+) -> HttpResponse:
+    """
+    Construct a response to a webhook event from a Thinkst canarytoken from
+    canarytokens.org. Canarytokens from Thinkst's paid product have a different
+    schema and should use the "thinkst" integration. See linked documentation
+    below for a schema:
+
+    https://help.canary.tools/hc/en-gb/articles/360002426577-How-do-I-configure-notifications-for-a-Generic-Webhook-
+    """
+    topic_name = "canarytoken alert"
+    time = message["time"].tame(check_string)
+    formatted_time = datetime_to_global_time(
+        datetime.fromisoformat(time.replace("(UTC)", "").strip() + "+00:00")
+    )
+    body = (
+        f"**:alert: Canarytoken has been triggered on {formatted_time}!**\n\n"
+        f"{message['memo'].tame(check_string)} \n\n"
+        f"[Manage this canarytoken]({message['manage_url'].tame(check_string)})"
+    )
+
+    if user_specified_topic is not None:
+        topic_name = user_specified_topic
+
+    check_send_webhook_message(request, user_profile, topic_name, body)
+    return json_success(request)