feat(api): manual updates

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 42
 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/imagekit-inc%2Fimagekit-3d7da4b8ef2ed30aa32c4fb3e98e498e67402e91aaa5fd4c628fc080bfe82ea1.yml
 openapi_spec_hash: aaa50fcbccec6f2cf1165f34bc6ac886
-config_hash: 84bf9f929b0248a6cdf2d526331ed8eb
+config_hash: 0f760028496146ece9431573b1ab0e46

pyproject.toml

@@ -40,6 +40,7 @@ Repository = "https://github.com/stainless-sdks/imagekit-python"
 
 [project.optional-dependencies]
 aiohttp = ["aiohttp", "httpx_aiohttp>=0.1.8"]
+webhooks = ["standardwebhooks"]
 
 [tool.rye]
 managed = true

requirements-dev.lock

@@ -28,11 +28,14 @@ async-timeout==5.0.1
     # via aiohttp
 attrs==25.3.0
     # via aiohttp
+    # via standardwebhooks
 certifi==2023.7.22
     # via httpcore
     # via httpx
 colorlog==6.7.0
     # via nox
+deprecated==1.2.18
+    # via standardwebhooks
 dirty-equals==0.6.0
 distlib==0.3.7
     # via virtualenv
@@ -56,6 +59,7 @@ httpx==0.28.1
     # via httpx-aiohttp
     # via imagekit
     # via respx
+    # via standardwebhooks
 httpx-aiohttp==0.1.8
     # via imagekit
 idna==3.4
@@ -102,6 +106,7 @@ pytest==8.3.3
 pytest-asyncio==0.24.0
 pytest-xdist==3.7.0
 python-dateutil==2.8.2
+    # via standardwebhooks
     # via time-machine
 pytz==2023.3.post1
     # via dirty-equals
@@ -115,10 +120,16 @@ six==1.16.0
 sniffio==1.3.0
     # via anyio
     # via imagekit
+standardwebhooks==1.0.0
+    # via imagekit
 time-machine==2.9.0
 tomli==2.0.2
     # via mypy
     # via pytest
+types-deprecated==1.2.15.20250304
+    # via standardwebhooks
+types-python-dateutil==2.9.0.20250822
+    # via standardwebhooks
 typing-extensions==4.12.2
     # via anyio
     # via imagekit
@@ -129,6 +140,8 @@ typing-extensions==4.12.2
     # via pyright
 virtualenv==20.24.5
     # via nox
+wrapt==1.17.3
+    # via deprecated
 yarl==1.20.0
     # via aiohttp
 zipp==3.17.0

requirements.lock

@@ -26,9 +26,12 @@ async-timeout==5.0.1
     # via aiohttp
 attrs==25.3.0
     # via aiohttp
+    # via standardwebhooks
 certifi==2023.7.22
     # via httpcore
     # via httpx
+deprecated==1.2.18
+    # via standardwebhooks
 distro==1.8.0
     # via imagekit
 exceptiongroup==1.2.2
@@ -43,6 +46,7 @@ httpcore==1.0.9
 httpx==0.28.1
     # via httpx-aiohttp
     # via imagekit
+    # via standardwebhooks
 httpx-aiohttp==0.1.8
     # via imagekit
 idna==3.4
@@ -59,14 +63,26 @@ pydantic==2.10.3
     # via imagekit
 pydantic-core==2.27.1
     # via pydantic
+python-dateutil==2.9.0.post0
+    # via standardwebhooks
+six==1.17.0
+    # via python-dateutil
 sniffio==1.3.0
     # via anyio
     # via imagekit
+standardwebhooks==1.0.0
+    # via imagekit
+types-deprecated==1.2.15.20250304
+    # via standardwebhooks
+types-python-dateutil==2.9.0.20250822
+    # via standardwebhooks
 typing-extensions==4.12.2
     # via anyio
     # via imagekit
     # via multidict
     # via pydantic
     # via pydantic-core
+wrapt==1.17.3
+    # via deprecated
 yarl==1.20.0
     # via aiohttp

src/imagekit/__init__.py

@@ -34,6 +34,7 @@
     InternalServerError,
     PermissionDeniedError,
     UnprocessableEntityError,
+    APIWebhookValidationError,
     APIResponseValidationError,
 )
 from ._base_client import DefaultHttpxClient, DefaultAioHttpClient, DefaultAsyncHttpxClient
@@ -55,6 +56,7 @@
     "APITimeoutError",
     "APIConnectionError",
     "APIResponseValidationError",
+    "APIWebhookValidationError",
     "BadRequestError",
     "AuthenticationError",
     "PermissionDeniedError",

src/imagekit/_client.py

@@ -64,12 +64,14 @@ class ImageKit(SyncAPIClient):
     # client options
     private_api_key: str
     password: str | None
+    webhook_secret: str | None
 
     def __init__(
         self,
         *,
         private_api_key: str | None = None,
         password: str | None = None,
+        webhook_secret: str | None = None,
         base_url: str | httpx.URL | None = None,
         timeout: Union[float, Timeout, None, NotGiven] = NOT_GIVEN,
         max_retries: int = DEFAULT_MAX_RETRIES,
@@ -94,6 +96,7 @@ def __init__(
         This automatically infers the following arguments from their corresponding environment variables if they are not provided:
         - `private_api_key` from `IMAGEKIT_PRIVATE_API_KEY`
         - `password` from `OPTIONAL_IMAGEKIT_IGNORES_THIS`
+        - `webhook_secret` from `IMAGEKIT_WEBHOOK_SECRET`
         """
         if private_api_key is None:
             private_api_key = os.environ.get("IMAGEKIT_PRIVATE_API_KEY")
@@ -107,6 +110,10 @@ def __init__(
             password = os.environ.get("OPTIONAL_IMAGEKIT_IGNORES_THIS") or "do_not_set"
         self.password = password
 
+        if webhook_secret is None:
+            webhook_secret = os.environ.get("IMAGEKIT_WEBHOOK_SECRET")
+        self.webhook_secret = webhook_secret
+
         if base_url is None:
             base_url = os.environ.get("IMAGE_KIT_BASE_URL")
         self._base_url_overridden = base_url is not None
@@ -174,6 +181,7 @@ def copy(
         *,
         private_api_key: str | None = None,
         password: str | None = None,
+        webhook_secret: str | None = None,
         base_url: str | httpx.URL | None = None,
         timeout: float | Timeout | None | NotGiven = NOT_GIVEN,
         http_client: httpx.Client | None = None,
@@ -209,6 +217,7 @@ def copy(
         client = self.__class__(
             private_api_key=private_api_key or self.private_api_key,
             password=password or self.password,
+            webhook_secret=webhook_secret or self.webhook_secret,
             base_url=base_url or self.base_url,
             timeout=self.timeout if isinstance(timeout, NotGiven) else timeout,
             http_client=http_client,
@@ -273,12 +282,14 @@ class AsyncImageKit(AsyncAPIClient):
     # client options
     private_api_key: str
     password: str | None
+    webhook_secret: str | None
 
     def __init__(
         self,
         *,
         private_api_key: str | None = None,
         password: str | None = None,
+        webhook_secret: str | None = None,
         base_url: str | httpx.URL | None = None,
         timeout: Union[float, Timeout, None, NotGiven] = NOT_GIVEN,
         max_retries: int = DEFAULT_MAX_RETRIES,
@@ -303,6 +314,7 @@ def __init__(
         This automatically infers the following arguments from their corresponding environment variables if they are not provided:
         - `private_api_key` from `IMAGEKIT_PRIVATE_API_KEY`
         - `password` from `OPTIONAL_IMAGEKIT_IGNORES_THIS`
+        - `webhook_secret` from `IMAGEKIT_WEBHOOK_SECRET`
         """
         if private_api_key is None:
             private_api_key = os.environ.get("IMAGEKIT_PRIVATE_API_KEY")
@@ -316,6 +328,10 @@ def __init__(
             password = os.environ.get("OPTIONAL_IMAGEKIT_IGNORES_THIS") or "do_not_set"
         self.password = password
 
+        if webhook_secret is None:
+            webhook_secret = os.environ.get("IMAGEKIT_WEBHOOK_SECRET")
+        self.webhook_secret = webhook_secret
+
         if base_url is None:
             base_url = os.environ.get("IMAGE_KIT_BASE_URL")
         self._base_url_overridden = base_url is not None
@@ -383,6 +399,7 @@ def copy(
         *,
         private_api_key: str | None = None,
         password: str | None = None,
+        webhook_secret: str | None = None,
         base_url: str | httpx.URL | None = None,
         timeout: float | Timeout | None | NotGiven = NOT_GIVEN,
         http_client: httpx.AsyncClient | None = None,
@@ -418,6 +435,7 @@ def copy(
         client = self.__class__(
             private_api_key=private_api_key or self.private_api_key,
             password=password or self.password,
+            webhook_secret=webhook_secret or self.webhook_secret,
             base_url=base_url or self.base_url,
             timeout=self.timeout if isinstance(timeout, NotGiven) else timeout,
             http_client=http_client,

src/imagekit/_exceptions.py

@@ -54,6 +54,10 @@ def __init__(self, response: httpx.Response, body: object | None, *, message: st
         self.status_code = response.status_code
 
 
+class APIWebhookValidationError(APIError):
+    pass
+
+
 class APIStatusError(APIError):
     """Raised when an API response has a status code of 4xx or 5xx."""
 

src/imagekit/resources/webhooks.py

@@ -3,10 +3,11 @@
 from __future__ import annotations
 
 import json
-from typing import cast
+from typing import Mapping, cast
 
 from .._models import construct_type
 from .._resource import SyncAPIResource, AsyncAPIResource
+from .._exceptions import ImageKitError
 from ..types.unwrap_webhook_event import UnwrapWebhookEvent
 from ..types.unsafe_unwrap_webhook_event import UnsafeUnwrapWebhookEvent
 
@@ -23,7 +24,24 @@ def unsafe_unwrap(self, payload: str) -> UnsafeUnwrapWebhookEvent:
             ),
         )
 
-    def unwrap(self, payload: str) -> UnwrapWebhookEvent:
+    def unwrap(self, payload: str, *, headers: Mapping[str, str], key: str | bytes | None = None) -> UnwrapWebhookEvent:
+        try:
+            from standardwebhooks import Webhook
+        except ImportError as exc:
+            raise ImageKitError("You need to install `imagekit[webhooks]` to use this method") from exc
+
+        if key is None:
+            key = self._client.webhook_secret
+            if key is None:
+                raise ValueError(
+                    "Cannot verify a webhook without a key on either the client's webhook_secret or passed in as an argument"
+                )
+
+        if not isinstance(headers, dict):
+            headers = dict(headers)
+
+        Webhook(key).verify(payload, headers)
+
         return cast(
             UnwrapWebhookEvent,
             construct_type(
@@ -43,7 +61,24 @@ def unsafe_unwrap(self, payload: str) -> UnsafeUnwrapWebhookEvent:
             ),
         )
 
-    def unwrap(self, payload: str) -> UnwrapWebhookEvent:
+    def unwrap(self, payload: str, *, headers: Mapping[str, str], key: str | bytes | None = None) -> UnwrapWebhookEvent:
+        try:
+            from standardwebhooks import Webhook
+        except ImportError as exc:
+            raise ImageKitError("You need to install `imagekit[webhooks]` to use this method") from exc
+
+        if key is None:
+            key = self._client.webhook_secret
+            if key is None:
+                raise ValueError(
+                    "Cannot verify a webhook without a key on either the client's webhook_secret or passed in as an argument"
+                )
+
+        if not isinstance(headers, dict):
+            headers = dict(headers)
+
+        Webhook(key).verify(payload, headers)
+
         return cast(
             UnwrapWebhookEvent,
             construct_type(

tests/api_resources/test_webhooks.py

@@ -3,17 +3,77 @@
 from __future__ import annotations
 
 import os
+from datetime import datetime, timezone
 
 import pytest
+import standardwebhooks
+
+from imagekit import ImageKit
 
 base_url = os.environ.get("TEST_API_BASE_URL", "http://127.0.0.1:4010")
 
 
 class TestWebhooks:
     parametrize = pytest.mark.parametrize("client", [False, True], indirect=True, ids=["loose", "strict"])
 
+    def test_method_unwrap(self, client: ImageKit) -> None:
+        key = b"secret"
+        hook = standardwebhooks.Webhook(key)
+
+        data = """{"id":"id","created_at":"2019-12-27T18:11:19.117Z","data":{"asset":{"url":"https://example.com"},"transformation":{"type":"video-transformation","options":{"audio_codec":"aac","auto_rotate":true,"format":"mp4","quality":0,"stream_protocol":"HLS","variants":["string"],"video_codec":"h264"}}},"request":{"url":"https://example.com","x_request_id":"x_request_id","user_agent":"user_agent"},"type":"video.transformation.accepted"}"""
+        msg_id = "1"
+        timestamp = datetime.now(tz=timezone.utc)
+        sig = hook.sign(msg_id=msg_id, timestamp=timestamp, data=data)
+        headers = {
+            "webhook-id": msg_id,
+            "webhook-timestamp": str(int(timestamp.timestamp())),
+            "webhook-signature": sig,
+        }
+
+        try:
+            _ = client.webhooks.unwrap(data, headers=headers, key=key)
+        except standardwebhooks.WebhookVerificationError as e:
+            raise AssertionError("Failed to unwrap valid webhook") from e
+
+        bad_headers = [
+            {**headers, "webhook-signature": hook.sign(msg_id=msg_id, timestamp=timestamp, data="xxx")},
+            {**headers, "webhook-id": "bad"},
+            {**headers, "webhook-timestamp": "0"},
+        ]
+        for bad_header in bad_headers:
+            with pytest.raises(standardwebhooks.WebhookVerificationError):
+                _ = client.webhooks.unwrap(data, headers=bad_header, key=key)
+
 
 class TestAsyncWebhooks:
     parametrize = pytest.mark.parametrize(
         "async_client", [False, True, {"http_client": "aiohttp"}], indirect=True, ids=["loose", "strict", "aiohttp"]
     )
+
+    def test_method_unwrap(self, client: ImageKit) -> None:
+        key = b"secret"
+        hook = standardwebhooks.Webhook(key)
+
+        data = """{"id":"id","created_at":"2019-12-27T18:11:19.117Z","data":{"asset":{"url":"https://example.com"},"transformation":{"type":"video-transformation","options":{"audio_codec":"aac","auto_rotate":true,"format":"mp4","quality":0,"stream_protocol":"HLS","variants":["string"],"video_codec":"h264"}}},"request":{"url":"https://example.com","x_request_id":"x_request_id","user_agent":"user_agent"},"type":"video.transformation.accepted"}"""
+        msg_id = "1"
+        timestamp = datetime.now(tz=timezone.utc)
+        sig = hook.sign(msg_id=msg_id, timestamp=timestamp, data=data)
+        headers = {
+            "webhook-id": msg_id,
+            "webhook-timestamp": str(int(timestamp.timestamp())),
+            "webhook-signature": sig,
+        }
+
+        try:
+            _ = client.webhooks.unwrap(data, headers=headers, key=key)
+        except standardwebhooks.WebhookVerificationError as e:
+            raise AssertionError("Failed to unwrap valid webhook") from e
+
+        bad_headers = [
+            {**headers, "webhook-signature": hook.sign(msg_id=msg_id, timestamp=timestamp, data="xxx")},
+            {**headers, "webhook-id": "bad"},
+            {**headers, "webhook-timestamp": "0"},
+        ]
+        for bad_header in bad_headers:
+            with pytest.raises(standardwebhooks.WebhookVerificationError):
+                _ = client.webhooks.unwrap(data, headers=bad_header, key=key)