allow @webhook_trigger functions to control the http response

Webhook handlers now wait for the decorated function and use its return
value to build the response: int -> Response(status=...), aiohttp.web.Response
-> as-is, None -> default 200. When multiple triggers share a webhook_id,
the first non-None return wins.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: JayNewstrom

custom_components/pyscript/decorator.py

@@ -264,6 +264,7 @@ async def _call(self, data: DispatchData) -> None:
                 # notify handlers with "None"
                 for result_handler_dec in result_handlers:
                     await result_handler_dec.handle_call_result(data, None)
+                data.set_result(None)
                 return
         # Fire an event indicating that pyscript is running
         # Note: the event must have an entity_id for logbook to work correctly.
@@ -279,7 +280,9 @@ async def _call(self, data: DispatchData) -> None:
             result = await data.call_ast_ctx.call_func(self.eval_func, None, **data.func_args)
             for result_handler_dec in result_handlers:
                 await result_handler_dec.handle_call_result(data, result)
+            data.set_result(result)
         except Exception as e:
+            data.set_result(None)
             await self.handle_exception(e)
 
     async def dispatch(self, data: DispatchData) -> None:
@@ -290,6 +293,7 @@ async def dispatch(self, data: DispatchData) -> None:
         for dec in decorators:
             if await dec.handle_dispatch(data) is False:
                 self.logger.debug("Trigger not active due to %s", dec)
+                data.set_result(None)
                 return
 
         action_ast_ctx = AstEval(

custom_components/pyscript/decorator_abc.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
+import asyncio
 from dataclasses import dataclass, field
 from enum import StrEnum
 import logging
@@ -46,6 +47,16 @@ class DispatchData:
     call_ast_ctx: AstEval | None = field(default=None, kw_only=True)
     hass_context: Context | None = field(default=None, kw_only=True)
 
+    # When set, the dispatch pipeline resolves this future with the
+    # decorated function's return value. Resolved with None if the
+    # function is skipped (guard rejection) or raises.
+    result_future: asyncio.Future[Any] | None = field(default=None, kw_only=True)
+
+    def set_result(self, value: Any) -> None:
+        """Resolve result_future with value if it is still pending."""
+        if self.result_future is not None and not self.result_future.done():
+            self.result_future.set_result(value)
+
 
 class Decorator(ABC):
     """Generic decorator abstraction."""

custom_components/pyscript/decorators/webhook.py

@@ -2,10 +2,11 @@
 
 from __future__ import annotations
 
+import asyncio
 import logging
-from typing import ClassVar
+from typing import Any, ClassVar
 
-from aiohttp import hdrs
+from aiohttp import hdrs, web
 import voluptuous as vol
 
 from homeassistant.components import webhook
@@ -32,12 +33,14 @@ class WebhookTriggerDecorator(TriggerDecorator, ExpressionDecorator, AutoKwargsD
         {
             vol.Optional("local_only", default=True): cv.boolean,
             vol.Optional("methods"): vol.All(list[str], [vol.In(SUPPORTED_METHODS)]),
+            vol.Optional("sets_http_response_code", default=False): cv.boolean,
         }
     )
 
     webhook_id: str
     local_only: bool
     methods: set[str]
+    sets_http_response_code: bool
 
     webhook_id2triggers: ClassVar[dict[str, set[WebhookTriggerDecorator]]] = {}
 
@@ -50,7 +53,7 @@ async def validate(self):
             self.create_expression(self.args[1])
 
     @staticmethod
-    async def _handler(_hass, webhook_id, request):
+    async def _handler(hass, webhook_id, request):
         func_args = {
             "trigger_type": "webhook",
             "webhook_id": webhook_id,
@@ -64,17 +67,59 @@ async def _handler(_hass, webhook_id, request):
             payload_multidict = await request.post()
             func_args["payload"] = {k: payload_multidict.getone(k) for k in payload_multidict.keys()}
 
+        response_future: asyncio.Future[Any] | None = None
+        futures: list[asyncio.Future[Any]] = []
         for trigger in WebhookTriggerDecorator.webhook_id2triggers.get(webhook_id, set()).copy():
             trigger_args = func_args.copy()
             if trigger.has_expression():
                 if not await trigger.check_expression_vars(trigger_args):
                     continue
-            await trigger.dispatch(DispatchData(trigger_args))
+            future: asyncio.Future[Any] = hass.loop.create_future()
+            if trigger.sets_http_response_code:
+                response_future = future
+            futures.append(future)
+            await trigger.dispatch(DispatchData(trigger_args, result_future=future))
+
+        if not futures:
+            return None
+
+        await asyncio.gather(*futures, return_exceptions=True)
+
+        if response_future is None:
+            return None
+        return WebhookTriggerDecorator.coerce_response(response_future.result())
+
+    @staticmethod
+    def coerce_response(value: Any) -> web.Response | None:
+        """Convert a webhook function return value to an aiohttp Response."""
+        if value is None:
+            return None
+        if isinstance(value, web.Response):
+            return value
+        # bool is a subclass of int; reject it so True/False don't become 1/0 status codes.
+        if isinstance(value, int) and not isinstance(value, bool):
+            return web.Response(status=value)
+        _LOGGER.warning(
+            "webhook function returned unsupported type %s; expected int status code or aiohttp.web.Response",
+            type(value).__name__,
+        )
+        return None
 
     @staticmethod
     def _add_trigger(trigger: WebhookTriggerDecorator) -> None:
         webhook_id = trigger.webhook_id
-        if webhook_id not in WebhookTriggerDecorator.webhook_id2triggers:
+        existing = WebhookTriggerDecorator.webhook_id2triggers.get(webhook_id)
+        if (
+            trigger.sets_http_response_code
+            and existing is not None
+            and any(t.sets_http_response_code for t in existing)
+        ):
+            raise ValueError(
+                f"webhook_id '{webhook_id}' already has a @webhook_trigger with "
+                f"sets_http_response_code=True; only one is allowed"
+            )
+
+        if existing is None:
             webhook.async_register(
                 trigger.dm.hass,
                 "pyscript",  # DOMAIN

custom_components/pyscript/stubs/pyscript_builtins.py

@@ -127,6 +127,7 @@ def webhook_trigger(
     str_expr: str | None = None,
     local_only: bool = True,
     methods: set[SUPPORTED_METHODS] | list[SUPPORTED_METHODS] = {"POST", "PUT"},
+    sets_http_response_code: bool = False,
     kwargs: dict | None = None,
 ) -> Callable[..., Any]:
     """Trigger when a request is made to a webhook endpoint.
@@ -136,6 +137,7 @@ def webhook_trigger(
         str_expr: Optional expression evaluated against ``trigger_type``, ``webhook_id``, ``request``, and ``payload``.
         local_only: If False, allow requests from anywhere on the internet.
         methods: HTTP methods to allow.
+        sets_http_response_code: If True, the function's return value drives the HTTP response (``int`` status code or ``aiohttp.web.Response``); at most one trigger per ``webhook_id`` may set this.
         kwargs: Extra keyword arguments merged into each invocation.
 
     Trigger kwargs include ``trigger_type="webhook"``, ``webhook_id``, the parsed payload fields, and ``request`` (the underlying ``aiohttp.web.Request``).

docs/reference.rst

@@ -915,6 +915,18 @@ To validate an HMAC signature on incoming requests, declare ``request`` in the f
           return
       log.info(f"verified webhook: {payload}")
 
+To control the HTTP response sent back to the webhook caller, opt in by passing ``sets_http_response_code=True``. The flagged function's return value then drives the response: ``None`` produces a ``200 OK``, an ``int`` sends back a response with that status code, and an ``aiohttp.web.Response`` allows full control over the body and headers. Return values from triggers without the flag are ignored. For example:
+
+.. code:: python
+
+  @webhook_trigger("myid", sets_http_response_code=True)
+  def webhook_check(payload):
+      if "token" not in payload:
+          return 401
+      return 204
+
+At most one ``@webhook_trigger`` per ``webhook_id`` may set ``sets_http_response_code=True``; declaring more than one is an error at setup time. The webhook handler waits for all decorated function(s) for the ``webhook_id`` to finish before responding, so use ``task.create()`` to fire-and-forget any long-running work.
+
 NOTE: A webhook_id can only be used by either a built-in Home Assistant automation or pyscript, but not both. Trying to use the same webhook_id in both will result in an error.
 
 @state_active

tests/test_decorator_manager.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import logging
 from typing import ClassVar
 from unittest.mock import patch
@@ -353,9 +354,15 @@ def make_dispatch_data(
     *,
     call_ast_ctx: DummyCallAstCtx | None = None,
     hass_context: Context | None = None,
+    result_future: asyncio.Future | None = None,
 ) -> DispatchData:
     """Build DispatchData from test doubles."""
-    return DispatchData(func_args, call_ast_ctx=call_ast_ctx, hass_context=hass_context)
+    return DispatchData(
+        func_args,
+        call_ast_ctx=call_ast_ctx,
+        hass_context=hass_context,
+        result_future=result_future,
+    )
 
 
 def setup_global_context_function_hass(hass: HomeAssistant, config_data: dict | None = None) -> None:
@@ -599,6 +606,77 @@ async def test_function_decorator_manager_logs_call_exception(hass):
     assert str(ast_ctx.logged_exceptions[0]) == "decorated call failed"
 
 
+@pytest.mark.asyncio
+async def test_function_decorator_manager_result_future_success(hass):
+    """Successful calls should resolve result_future with the function's return value."""
+    DecoratorManager.hass = hass
+    manager = FunctionDecoratorManager(DummyAstCtx(), DummyEvalFuncVar())
+    call_ast_ctx = DummyCallAstCtx(result=201)
+    future: asyncio.Future = hass.loop.create_future()
+
+    with patch.object(Function, "store_hass_context"):
+        await call_function_manager(
+            manager,
+            make_dispatch_data(
+                {"arg1": 1},
+                call_ast_ctx=call_ast_ctx,
+                hass_context=Context(id="call-parent"),
+                result_future=future,
+            ),
+        )
+        await hass.async_block_till_done()
+
+    assert future.done()
+    assert future.result() == 201
+
+
+@pytest.mark.asyncio
+async def test_function_decorator_manager_result_future_cancel(hass):
+    """When a call handler cancels, result_future should resolve to None."""
+    DecoratorManager.hass = hass
+    manager = FunctionDecoratorManager(DummyAstCtx(), DummyEvalFuncVar())
+    manager.add(make_cancel_call_handler())
+    future: asyncio.Future = hass.loop.create_future()
+
+    await call_function_manager(
+        manager,
+        make_dispatch_data(
+            {"arg1": 1},
+            call_ast_ctx=DummyCallAstCtx(result="unused"),
+            hass_context=Context(id="call-parent"),
+            result_future=future,
+        ),
+    )
+
+    assert future.done()
+    assert future.result() is None
+
+
+@pytest.mark.asyncio
+async def test_function_decorator_manager_result_future_exception(hass):
+    """When the decorated function raises, result_future should resolve to None."""
+    DecoratorManager.hass = hass
+    ast_ctx = DummyAstCtx()
+    manager = FunctionDecoratorManager(ast_ctx, DummyEvalFuncVar())
+    call_ast_ctx = DummyCallAstCtx(exc=RuntimeError("boom"))
+    future: asyncio.Future = hass.loop.create_future()
+
+    with patch.object(Function, "store_hass_context"):
+        await call_function_manager(
+            manager,
+            make_dispatch_data(
+                {"arg1": 1},
+                call_ast_ctx=call_ast_ctx,
+                hass_context=Context(id="call-parent"),
+                result_future=future,
+            ),
+        )
+
+    assert future.done()
+    assert future.result() is None
+    assert len(ast_ctx.logged_exceptions) == 1
+
+
 def test_decorator_registry_register_requires_name():
     """Registry should reject decorators without a declared name."""