address feedback, better webhooks

Author: vdusek

src/apify_client/_models.py

@@ -15,7 +15,7 @@
 from apify_client._models_generated import ActorJobStatus, WebhookCreate
 
 if TYPE_CHECKING:
-    from apify_client._typeddicts_generated import WebhookCreateDict
+    from apify_client._types import WebhooksList
 
 
 @docs_group('Models')
@@ -71,20 +71,25 @@ class WebhookRepresentationList(RootModel[list[WebhookRepresentation]]):
     """List of webhook representations with base64 encoding support."""
 
     @classmethod
-    def from_webhooks(cls, webhooks: list[WebhookCreate] | list[WebhookCreateDict]) -> WebhookRepresentationList:
-        """Construct from a list of `WebhookCreate` models or `WebhookCreateDict` TypedDicts.
+    def from_webhooks(cls, webhooks: WebhooksList) -> WebhookRepresentationList:
+        """Construct from a list of webhooks.
 
-        Dicts are validated directly as `WebhookRepresentation`, so only the minimal ad-hoc webhook fields
-        (`event_types`, `request_url`, and optionally `payload_template`/`headers_template`) are required.
+        See `WebhooksList` for the accepted shapes. `WebhookRepresentation` instances are used as-is; all
+        other shapes are validated into `WebhookRepresentation`, keeping only its fields and ignoring any
+        extras (e.g. `condition`).
         """
         representations = list[WebhookRepresentation]()
 
         for webhook in webhooks:
-            if isinstance(webhook, WebhookCreate):
+            if isinstance(webhook, WebhookRepresentation):
+                representations.append(webhook)
+            elif isinstance(webhook, WebhookCreate):
                 webhook_dict = webhook.model_dump(mode='json', exclude_none=True)
-                representations.append(WebhookRepresentation.model_validate(webhook_dict))
+                webhook_representation = WebhookRepresentation.model_validate(webhook_dict)
+                representations.append(webhook_representation)
             else:
-                representations.append(WebhookRepresentation.model_validate(webhook))
+                webhook_representation = WebhookRepresentation.model_validate(webhook)
+                representations.append(webhook_representation)
 
         return cls(representations)
 

src/apify_client/_resource_clients/actor.py

@@ -24,7 +24,6 @@
     RunOrigin,
     RunResponse,
     UpdateActorRequest,
-    WebhookCreate,
 )
 from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
 from apify_client._utils import encode_key_value_store_record_value, response_to_dict, to_seconds
@@ -51,8 +50,7 @@
         WebhookCollectionClient,
         WebhookCollectionClientAsync,
     )
-    from apify_client._typeddicts_generated import WebhookCreateDict
-    from apify_client._types import Timeout
+    from apify_client._types import Timeout, WebhooksList
 
 _PricingInfo = (
     PayPerEventActorPricingInfo
@@ -231,7 +229,7 @@ def start(
         run_timeout: timedelta | None = None,
         force_permission_level: ActorPermissionLevel | None = None,
         wait_for_finish: int | None = None,
-        webhooks: list[WebhookCreate] | list[WebhookCreateDict] | None = None,
+        webhooks: WebhooksList | None = None,
         timeout: Timeout = 'medium',
     ) -> Run:
         """Start the Actor and immediately return the Run object.
@@ -305,7 +303,7 @@ def call(
         restart_on_error: bool | None = None,
         memory_mbytes: int | None = None,
         run_timeout: timedelta | None = None,
-        webhooks: list[WebhookCreate] | list[WebhookCreateDict] | None = None,
+        webhooks: WebhooksList | None = None,
         force_permission_level: ActorPermissionLevel | None = None,
         wait_duration: timedelta | None = None,
         logger: Logger | None | Literal['default'] = 'default',
@@ -727,7 +725,7 @@ async def start(
         run_timeout: timedelta | None = None,
         force_permission_level: ActorPermissionLevel | None = None,
         wait_for_finish: int | None = None,
-        webhooks: list[WebhookCreate] | list[WebhookCreateDict] | None = None,
+        webhooks: WebhooksList | None = None,
         timeout: Timeout = 'medium',
     ) -> Run:
         """Start the Actor and immediately return the Run object.
@@ -801,7 +799,7 @@ async def call(
         restart_on_error: bool | None = None,
         memory_mbytes: int | None = None,
         run_timeout: timedelta | None = None,
-        webhooks: list[WebhookCreate] | list[WebhookCreateDict] | None = None,
+        webhooks: WebhooksList | None = None,
         force_permission_level: ActorPermissionLevel | None = None,
         wait_duration: timedelta | None = None,
         logger: Logger | None | Literal['default'] = 'default',

src/apify_client/_resource_clients/task.py

@@ -14,7 +14,6 @@
     TaskOptions,
     TaskResponse,
     UpdateTaskRequest,
-    WebhookCreate,
 )
 from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
 from apify_client._utils import catch_not_found_or_throw, response_to_dict, to_seconds
@@ -32,8 +31,8 @@
         WebhookCollectionClient,
         WebhookCollectionClientAsync,
     )
-    from apify_client._typeddicts_generated import TaskInputDict, WebhookCreateDict
-    from apify_client._types import Timeout
+    from apify_client._typeddicts_generated import TaskInputDict
+    from apify_client._types import Timeout, WebhooksList
 
 
 @docs_group('Resource clients')
@@ -163,7 +162,7 @@ def start(
         run_timeout: timedelta | None = None,
         restart_on_error: bool | None = None,
         wait_for_finish: int | None = None,
-        webhooks: list[WebhookCreate] | list[WebhookCreateDict] | None = None,
+        webhooks: WebhooksList | None = None,
         timeout: Timeout = 'medium',
     ) -> Run:
         """Start the task and immediately return the Run object.
@@ -230,7 +229,7 @@ def call(
         memory_mbytes: int | None = None,
         run_timeout: timedelta | None = None,
         restart_on_error: bool | None = None,
-        webhooks: list[WebhookCreate] | list[WebhookCreateDict] | None = None,
+        webhooks: WebhooksList | None = None,
         wait_duration: timedelta | None = None,
         timeout: Timeout = 'no_timeout',
     ) -> Run | None:
@@ -487,7 +486,7 @@ async def start(
         run_timeout: timedelta | None = None,
         restart_on_error: bool | None = None,
         wait_for_finish: int | None = None,
-        webhooks: list[WebhookCreate] | list[WebhookCreateDict] | None = None,
+        webhooks: WebhooksList | None = None,
         timeout: Timeout = 'medium',
     ) -> Run:
         """Start the task and immediately return the Run object.
@@ -554,7 +553,7 @@ async def call(
         memory_mbytes: int | None = None,
         run_timeout: timedelta | None = None,
         restart_on_error: bool | None = None,
-        webhooks: list[WebhookCreate] | list[WebhookCreateDict] | None = None,
+        webhooks: WebhooksList | None = None,
         wait_duration: timedelta | None = None,
         timeout: Timeout = 'no_timeout',
     ) -> Run | None:

src/apify_client/_typeddicts.py

@@ -40,3 +40,25 @@ class RequestDeleteInputDict(TypedDict):
 
     unique_key: NotRequired[str | None]
     """A unique key used for request de-duplication."""
+
+
+@docs_group('Typed dicts')
+class WebhookRepresentationDict(TypedDict):
+    """TypedDict counterpart of `WebhookRepresentation` for ad-hoc webhooks.
+
+    Captures the minimal shape the Apify API actually requires when attaching ad-hoc webhooks to a run:
+    only `event_types` and `request_url` are mandatory. Unlike `WebhookCreateDict`, there is no `condition`
+    field — the API does not use it for ad-hoc webhooks.
+    """
+
+    event_types: list[str]
+    """The list of Actor events that trigger this webhook."""
+
+    request_url: str
+    """The URL to which the webhook sends its payload."""
+
+    payload_template: NotRequired[str | None]
+    """Optional template for the JSON payload sent by the webhook."""
+
+    headers_template: NotRequired[str | None]
+    """Optional template for the HTTP headers sent by the webhook."""

src/apify_client/_types.py

@@ -3,6 +3,22 @@
 from datetime import timedelta
 from typing import Literal
 
+from apify_client._models import WebhookRepresentation
+from apify_client._models_generated import WebhookCreate
+from apify_client._typeddicts import WebhookRepresentationDict
+from apify_client._typeddicts_generated import WebhookCreateDict
+
+WebhooksList = (
+    list[WebhookCreate] | list[WebhookCreateDict] | list[WebhookRepresentation] | list[WebhookRepresentationDict]
+)
+"""Type for the `webhooks` parameter on resource-client `start`/`call` methods and `from_webhooks`.
+
+`WebhookRepresentation` / `WebhookRepresentationDict` are the minimal ad-hoc webhook shape (only
+`event_types` and `request_url` required). `WebhookCreate` / `WebhookCreateDict` are accepted so a
+persistent-webhook definition can be reused; their fields not relevant to ad-hoc webhooks (e.g.
+`condition`) are ignored at runtime.
+"""
+
 Timeout = timedelta | Literal['no_timeout', 'short', 'medium', 'long']
 """Type for the `timeout` parameter on resource client methods.
 

tests/unit/test_utils.py

@@ -26,7 +26,7 @@
 from apify_client.errors import ApifyApiError, InvalidResponseBodyError
 
 if TYPE_CHECKING:
-    from apify_client._typeddicts_generated import WebhookCreateDict
+    from apify_client._typeddicts import WebhookRepresentationDict
 
 
 def test_to_safe_id() -> None:
@@ -59,16 +59,14 @@ def test_webhook_representation_list_to_base64() -> None:
 
 
 def test_webhook_representation_list_from_dicts() -> None:
-    """Test that from_webhooks accepts plain dicts typed as WebhookCreateDict."""
-    webhooks: list[WebhookCreateDict] = [
+    """Test that from_webhooks accepts plain dicts typed as WebhookRepresentationDict."""
+    webhooks: list[WebhookRepresentationDict] = [
         {
             'event_types': ['ACTOR.RUN.CREATED'],
-            'condition': {},
             'request_url': 'https://example.com/run-created',
         },
         {
             'event_types': ['ACTOR.RUN.SUCCEEDED'],
-            'condition': {},
             'request_url': 'https://example.com/run-succeeded',
             'payload_template': '{"hello": "world"}',
         },