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

zerver/webhooks/homeassistant/doc.md

@@ -0,0 +1,45 @@
+1. {!create-channel.md!}
+
+1. {!create-an-incoming-webhook.md!}
+
+1. In Home Assistant, you need to add the `notify` service to your
+    `configuration.yaml` file.  This should look something like this:
+
+    ```
+    notify:
+      - platform: rest
+        resource: http: {{ external_api_uri }}v1/external/homeassistant?api_key=<API key>
+        method: POST_JSON
+        title_param_name: topic
+    ```
+
+1. The `api_key` parameter should correspond to your bot's key. The `stream`
+    parameter is not necessarily required; if not given, it will default to
+    the `homeassistant` channel.
+
+1. And the URL under `resource` should start with:
+
+    `{{ api_url }}/v1/external/homeassistant`
+
+1. Finally, you need to configure a trigger for the service by adding
+    an automation entry in the HomeAssistant `configuration.yaml` file.
+
+    ```
+    automation:
+      trigger:
+        platform: sun
+        event: sunrise
+      action:
+        - service: notify.notify
+          data:
+            message: "It will be 30 degrees Celsius out there today!"
+            title: "Weather forecast"
+    ```
+
+    The `data` object takes at least a `message` property and an optional
+    `title` parameter which will be the conversation topic and which defaults
+    to `homeassistant` if not given.
+
+{!congrats.md!}
+
+![](/static/images/integrations/homeassistant/001.png)

zerver/webhooks/homeassistant/fixtures/reqwithtitle.json

@@ -0,0 +1,4 @@
+{
+    "topic": "Weather forecast",
+    "message": "It will be 30 degrees Celsius out there today!"
+}

zerver/webhooks/homeassistant/fixtures/simplereq.json

@@ -0,0 +1,3 @@
+{
+  "message": "The sun will be shining today!"
+}

zerver/webhooks/homeassistant/tests.py

@@ -0,0 +1,25 @@
+from zerver.lib.test_classes import WebhookTestCase
+
+
+class HomeAssistantHookTests(WebhookTestCase):
+    def test_simplereq(self) -> None:
+        expected_topic_name = "homeassistant"
+        expected_message = "The sun will be shining today!"
+
+        self.check_webhook(
+            "simplereq",
+            expected_topic_name,
+            expected_message,
+            content_type="application/x-www-form-urlencoded",
+        )
+
+    def test_req_with_title(self) -> None:
+        expected_topic_name = "Weather forecast"
+        expected_message = "It will be 30 degrees Celsius out there today!"
+
+        self.check_webhook(
+            "reqwithtitle",
+            expected_topic_name,
+            expected_message,
+            content_type="application/x-www-form-urlencoded",
+        )

zerver/webhooks/homeassistant/view.py

@@ -0,0 +1,32 @@
+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("HomeAssistant")
+@typed_endpoint
+def api_homeassistant_webhook(
+    request: HttpRequest,
+    user_profile: UserProfile,
+    *,
+    payload: JsonBodyPayload[WildValue],
+) -> HttpResponse:
+    # construct the body of the message
+    body = payload["message"].tame(check_string)
+
+    # set the topic to the topic parameter, if given
+    if "topic" in payload:
+        topic_name = payload["topic"].tame(check_string)
+    else:
+        topic_name = "homeassistant"
+
+    # send the message
+    check_send_webhook_message(request, user_profile, topic_name, body)
+
+    # return json result
+    return json_success(request)