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

zerver/webhooks/helloworld/doc.md

@@ -0,0 +1,44 @@
+# Zulip Hello World integration
+
+Learn how Zulip integrations work with this simple Hello World example!
+
+This webhook is Zulip's official [example integration][incoming-webhooks-walkthrough].
+
+{start_tabs}
+
+1. The Hello World webhook will use the `test` channel, which is created
+    by default in the Zulip development environment. If you are running
+    Zulip in production, you should make sure that this channel exists.
+
+1. {!create-an-incoming-webhook.md!}
+
+1. {!generate-webhook-url-basic.md!}
+
+1. To trigger a notification using this example webhook, you can use
+    `send_webhook_fixture_message` from a [Zulip development
+    environment](https://zulip.readthedocs.io/en/latest/development/overview.html):
+
+    ```
+        (zulip-server) vagrant@vagrant:/srv/zulip$
+        ./manage.py send_webhook_fixture_message \
+        > --fixture=zerver/tests/fixtures/helloworld/hello.json \
+        > '--url=http://localhost:9991/api{{ integration_url }}?api_key=abcdefgh&stream=channel%20name;'
+    ```
+
+    Or, use curl:
+
+    ```
+    curl -X POST -H "Content-Type: application/json" -d '{ "featured_title":"Marilyn Monroe", "featured_url":"https://en.wikipedia.org/wiki/Marilyn_Monroe" }' http://localhost:9991/api{{ integration_url }}?api_key=abcdefgh&stream=channel%20name;
+    ```
+
+{end_tabs}
+
+{!congrats.md!}
+
+![](/static/images/integrations/helloworld/001.png)
+
+### Related documentation
+
+{!webhooks-url-specification.md!}
+
+[incoming-webhooks-walkthrough]: https://zulip.readthedocs.io/en/latest/webhooks/incoming-webhooks-walkthrough.html

zerver/webhooks/helloworld/fixtures/goodbye.json

@@ -0,0 +1,4 @@
+{
+  "featured_title":"Goodbye",
+  "featured_url":"https://en.wikipedia.org/wiki/Goodbye"
+}

zerver/webhooks/helloworld/fixtures/hello.json

@@ -0,0 +1,4 @@
+{
+  "featured_title":"Marilyn Monroe",
+  "featured_url":"https://en.wikipedia.org/wiki/Marilyn_Monroe"
+}

zerver/webhooks/helloworld/tests.py

@@ -0,0 +1,73 @@
+from django.conf import settings
+
+from zerver.lib.test_classes import WebhookTestCase
+from zerver.models.realms import get_realm
+from zerver.models.users import get_system_bot
+
+
+class HelloWorldHookTests(WebhookTestCase):
+    DIRECT_MESSAGE_URL_TEMPLATE = "/api/v1/external/helloworld?&api_key={api_key}"
+
+    # Note: Include a test function per each distinct message condition your integration supports
+    def test_hello_message(self) -> None:
+        expected_topic_name = "Hello World"
+        expected_message = "Hello! I am happy to be here! :smile:\nThe Wikipedia featured article for today is **[Marilyn Monroe](https://en.wikipedia.org/wiki/Marilyn_Monroe)**"
+
+        # use fixture named hello.json
+        self.check_webhook(
+            "hello",
+            expected_topic_name,
+            expected_message,
+            content_type="application/x-www-form-urlencoded",
+        )
+
+    def test_goodbye_message(self) -> None:
+        expected_topic_name = "Hello World"
+        expected_message = "Hello! I am happy to be here! :smile:\nThe Wikipedia featured article for today is **[Goodbye](https://en.wikipedia.org/wiki/Goodbye)**"
+
+        # use fixture named goodbye.json
+        self.check_webhook(
+            "goodbye",
+            expected_topic_name,
+            expected_message,
+            content_type="application/x-www-form-urlencoded",
+        )
+
+    def test_pm_to_bot_owner(self) -> None:
+        # Note that this is really just a test for check_send_webhook_message
+        self.url_template = self.DIRECT_MESSAGE_URL_TEMPLATE
+        self.url = self.build_webhook_url()
+        expected_message = "Hello! I am happy to be here! :smile:\nThe Wikipedia featured article for today is **[Goodbye](https://en.wikipedia.org/wiki/Goodbye)**"
+
+        self.send_and_test_private_message(
+            "goodbye",
+            expected_message=expected_message,
+            content_type="application/x-www-form-urlencoded",
+        )
+
+    def test_stream_error_pm_to_bot_owner(self) -> None:
+        # Note that this is really just a test for check_send_webhook_message
+        self.channel_name = "nonexistent"
+        self.url = self.build_webhook_url()
+        realm = get_realm("zulip")
+        notification_bot = get_system_bot(settings.NOTIFICATION_BOT, realm.id)
+        expected_message = "Your bot `webhook-bot@zulip.com` tried to send a message to channel #**nonexistent**, but that channel does not exist. Click [here](#channels/new) to create it."
+        self.send_and_test_private_message(
+            "goodbye",
+            expected_message=expected_message,
+            content_type="application/x-www-form-urlencoded",
+            sender=notification_bot,
+        )
+
+    def test_custom_topic(self) -> None:
+        # Note that this is really just a test for check_send_webhook_message
+        expected_topic_name = "Custom Topic"
+        self.url = self.build_webhook_url(topic=expected_topic_name)
+        expected_message = "Hello! I am happy to be here! :smile:\nThe Wikipedia featured article for today is **[Goodbye](https://en.wikipedia.org/wiki/Goodbye)**"
+
+        self.check_webhook(
+            "goodbye",
+            expected_topic_name,
+            expected_message,
+            content_type="application/x-www-form-urlencoded",
+        )

zerver/webhooks/helloworld/view.py

@@ -0,0 +1,38 @@
+# Webhooks for external integrations.
+
+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 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("HelloWorld")
+@typed_endpoint
+def api_helloworld_webhook(
+    request: HttpRequest,
+    user_profile: UserProfile,
+    *,
+    payload: JsonBodyPayload[WildValue],
+) -> HttpResponse:
+    # construct the body of the message
+    body = "Hello! I am happy to be here! :smile:"
+
+    # try to add the Wikipedia article of the day
+    body_template = (
+        "\nThe Wikipedia featured article for today is **[{featured_title}]({featured_url})**"
+    )
+    body += body_template.format(
+        featured_title=payload["featured_title"].tame(check_string),
+        featured_url=payload["featured_url"].tame(check_string),
+    )
+
+    topic_name = "Hello World"
+
+    # send the message
+    check_send_webhook_message(request, user_profile, topic_name, body)
+
+    return json_success(request)