refactor: replace encode_webhook_list_to_base64 with WebhookRepresentationList model

Introduce `WebhookRepresentation` and `WebhookRepresentationList` Pydantic
models in `_internal_models.py` to replace the standalone utility function.
The encoding logic now lives as methods on the model (`to_base64`,
`encode_to_base64`).

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

Author: vdusek

src/apify_client/_internal_models.py

@@ -2,9 +2,13 @@
 
 from __future__ import annotations
 
-from pydantic import BaseModel, ConfigDict
+import json
+from base64 import b64encode
+from typing import Annotated, overload
 
-from apify_client._models import ActorJobStatus  # noqa: TC001
+from pydantic import BaseModel, ConfigDict, Field, RootModel
+
+from apify_client._models import ActorJobStatus, WebhookCreate
 
 
 class ActorJob(BaseModel):
@@ -27,3 +31,58 @@ class ActorJobResponse(BaseModel):
     model_config = ConfigDict(extra='allow')
 
     data: ActorJob
+
+
+class WebhookRepresentation(BaseModel):
+    """Representation of a webhook for base64-encoded API transmission.
+
+    Contains only the fields needed for the webhook payload sent via query parameters.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra='ignore')
+
+    event_types: Annotated[list[str], Field(alias='eventTypes')]
+    request_url: Annotated[str, Field(alias='requestUrl')]
+    payload_template: Annotated[str | None, Field(alias='payloadTemplate')] = None
+    headers_template: Annotated[str | None, Field(alias='headersTemplate')] = None
+
+
+class WebhookRepresentationList(RootModel[list[WebhookRepresentation]]):
+    """List of webhook representations with base64 encoding support."""
+
+    @classmethod
+    def from_webhooks(cls, webhooks: list[dict | WebhookCreate]) -> WebhookRepresentationList:
+        """Construct from a list of webhook dictionaries or `WebhookCreate` models."""
+        representations = []
+        for webhook in webhooks:
+            webhook_dict = webhook.model_dump(exclude_none=True) if isinstance(webhook, WebhookCreate) else webhook
+            representations.append(WebhookRepresentation.model_validate(webhook_dict))
+        return cls(representations)
+
+    def to_base64(self) -> str:
+        """Encode this list of webhook representations to a base64 string."""
+        data = [r.model_dump(by_alias=True, exclude_none=True) for r in self.root]
+        return b64encode(json.dumps(data).encode('utf-8')).decode('ascii')
+
+    @overload
+    @classmethod
+    def encode_to_base64(cls, webhooks: None) -> None: ...
+
+    @overload
+    @classmethod
+    def encode_to_base64(cls, webhooks: list[dict | WebhookCreate]) -> str: ...
+
+    @classmethod
+    def encode_to_base64(cls, webhooks: list[dict | WebhookCreate] | None) -> str | None:
+        """Encode a list of webhook dictionaries or `WebhookCreate` models to base64 for API transmission.
+
+        Args:
+            webhooks: A list of webhook dictionaries or `WebhookCreate` models with keys like
+                `event_types`, `request_url`, etc. If None, returns None.
+
+        Returns:
+            A base64-encoded JSON string, or None if webhooks is None.
+        """
+        if webhooks is None:
+            return None
+        return cls.from_webhooks(webhooks).to_base64()

src/apify_client/_resource_clients/actor.py

@@ -5,6 +5,7 @@
 from pydantic import TypeAdapter
 
 from apify_client._docs import docs_group
+from apify_client._internal_models import WebhookRepresentationList
 from apify_client._models import (
     Actor,
     ActorPermissionLevel,
@@ -28,7 +29,6 @@
 from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
 from apify_client._utils import (
     encode_key_value_store_record_value,
-    encode_webhook_list_to_base64,
     response_to_dict,
     to_seconds,
 )
@@ -271,7 +271,7 @@ def start(
             timeout=to_seconds(timeout, as_int=True),
             waitForFinish=wait_for_finish,
             forcePermissionLevel=force_permission_level.value if force_permission_level is not None else None,
-            webhooks=encode_webhook_list_to_base64(webhooks),
+            webhooks=WebhookRepresentationList.encode_to_base64(webhooks),
         )
 
         response = self._http_client.call(
@@ -736,7 +736,7 @@ async def start(
             timeout=to_seconds(timeout, as_int=True),
             waitForFinish=wait_for_finish,
             forcePermissionLevel=force_permission_level.value if force_permission_level is not None else None,
-            webhooks=encode_webhook_list_to_base64(webhooks),
+            webhooks=WebhookRepresentationList.encode_to_base64(webhooks),
         )
 
         response = await self._http_client.call(

src/apify_client/_resource_clients/task.py

@@ -3,6 +3,7 @@
 from typing import TYPE_CHECKING, Any
 
 from apify_client._docs import docs_group
+from apify_client._internal_models import WebhookRepresentationList
 from apify_client._models import (
     ActorStandby,
     Run,
@@ -18,7 +19,6 @@
 from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
 from apify_client._utils import (
     catch_not_found_or_throw,
-    encode_webhook_list_to_base64,
     response_to_dict,
     to_seconds,
 )
@@ -198,7 +198,7 @@ def start(
             timeout=to_seconds(timeout, as_int=True),
             restartOnError=restart_on_error,
             waitForFinish=wait_for_finish,
-            webhooks=encode_webhook_list_to_base64(webhooks),
+            webhooks=WebhookRepresentationList.encode_to_base64(webhooks),
         )
 
         response = self._http_client.call(
@@ -502,7 +502,7 @@ async def start(
             timeout=to_seconds(timeout, as_int=True),
             restartOnError=restart_on_error,
             waitForFinish=wait_for_finish,
-            webhooks=encode_webhook_list_to_base64(webhooks),
+            webhooks=WebhookRepresentationList.encode_to_base64(webhooks),
         )
 
         response = await self._http_client.call(

src/apify_client/_utils.py

@@ -7,14 +7,13 @@
 import string
 import time
 import warnings
-from base64 import b64encode, urlsafe_b64encode
+from base64 import urlsafe_b64encode
 from http import HTTPStatus
 from typing import TYPE_CHECKING, Any, Literal, TypeVar, overload
 
 import impit
 
 from apify_client._consts import OVERRIDABLE_DEFAULT_HEADERS
-from apify_client._models import WebhookCreate
 from apify_client.errors import InvalidResponseBodyError
 
 if TYPE_CHECKING:
@@ -70,48 +69,6 @@ def catch_not_found_or_throw(exc: ApifyApiError) -> None:
         raise exc
 
 
-@overload
-def encode_webhook_list_to_base64(webhooks: None) -> None: ...
-
-
-@overload
-def encode_webhook_list_to_base64(webhooks: list[dict | WebhookCreate]) -> str: ...
-
-
-def encode_webhook_list_to_base64(webhooks: list[dict | WebhookCreate] | None) -> str | None:
-    """Encode a list of webhook dictionaries or `WebhookCreate` models to base64 for API transmission.
-
-    Args:
-        webhooks: A list of webhook dictionaries or `WebhookCreate` models with keys like
-            "event_types", "request_url", etc. If None, returns None.
-
-    Returns:
-        A base64-encoded JSON string, or None if webhooks is None.
-    """
-    if webhooks is None:
-        return None
-
-    data = list[dict]()
-
-    for webhook in webhooks:
-        webhook_dict = webhook.model_dump(exclude_none=True) if isinstance(webhook, WebhookCreate) else webhook
-
-        webhook_representation = {
-            'eventTypes': list(webhook_dict['event_types']),
-            'requestUrl': webhook_dict['request_url'],
-        }
-
-        if 'payload_template' in webhook_dict:
-            webhook_representation['payloadTemplate'] = webhook_dict['payload_template']
-
-        if 'headers_template' in webhook_dict:
-            webhook_representation['headersTemplate'] = webhook_dict['headers_template']
-
-        data.append(webhook_representation)
-
-    return b64encode(json.dumps(data).encode('utf-8')).decode('ascii')
-
-
 def encode_key_value_store_record_value(value: Any, content_type: str | None = None) -> tuple[Any, str]:
     """Encode a value for storage in a key-value store record.
 

tests/unit/test_utils.py

@@ -6,6 +6,7 @@
 import impit
 import pytest
 
+from apify_client._internal_models import WebhookRepresentationList
 from apify_client._models import WebhookEventType
 from apify_client._resource_clients._resource_client import ResourceClientBase
 from apify_client._utils import (
@@ -14,7 +15,6 @@
     create_storage_content_signature,
     encode_base62,
     encode_key_value_store_record_value,
-    encode_webhook_list_to_base64,
     is_retryable_error,
     response_to_dict,
     response_to_list,
@@ -31,9 +31,9 @@ def test_to_safe_id() -> None:
 
 
 def test_encode_webhook_list_to_base64() -> None:
-    assert encode_webhook_list_to_base64([]) == 'W10='
+    assert WebhookRepresentationList.encode_to_base64([]) == 'W10='
     assert (
-        encode_webhook_list_to_base64(
+        WebhookRepresentationList.encode_to_base64(
             [
                 {
                     'event_types': [WebhookEventType.ACTOR_RUN_CREATED],