feat(api): add webhook schemas to SDKs - add parse and parse_unsafe

chore: replace custom webhook signature verification with standardwebhooks

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 175
 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/lithic%2Flithic-abe6a4f82f696099fa8ecb1cc44f08979e17d56578ae7ea68b0e9182e21df508.yml
 openapi_spec_hash: d2ce51592a9a234c6f34a1168a31f91f
-config_hash: 739714a3fead0b26ee3a3b7bc51081f6
+config_hash: f4b1d2f464e80527f970de61cba0c52f

api.md

@@ -820,3 +820,122 @@ Methods:
 
 - <code title="get /v1/account_activity">client.account_activity.<a href="./src/lithic/resources/account_activity.py">list</a>(\*\*<a href="src/lithic/types/account_activity_list_params.py">params</a>) -> <a href="./src/lithic/types/account_activity_list_response.py">SyncCursorPage[AccountActivityListResponse]</a></code>
 - <code title="get /v1/account_activity/{transaction_token}">client.account_activity.<a href="./src/lithic/resources/account_activity.py">retrieve_transaction</a>(transaction_token) -> <a href="./src/lithic/types/account_activity_retrieve_transaction_response.py">AccountActivityRetrieveTransactionResponse</a></code>
+
+# Webhooks
+
+Types:
+
+```python
+from lithic.types import (
+    AccountHolderCreatedWebhookEvent,
+    AccountHolderUpdatedWebhookEvent,
+    AccountHolderVerificationWebhookEvent,
+    AccountHolderDocumentUpdatedWebhookEvent,
+    AsaRequestWebhookEvent,
+    TokenizationDecisioningRequestWebhookEvent,
+    AuthRulesBacktestReportCreatedWebhookEvent,
+    BalanceUpdatedWebhookEvent,
+    BookTransferTransactionCreatedWebhookEvent,
+    BookTransferTransactionUpdatedWebhookEvent,
+    CardCreatedWebhookEvent,
+    CardConvertedWebhookEvent,
+    CardRenewedWebhookEvent,
+    CardReissuedWebhookEvent,
+    CardShippedWebhookEvent,
+    CardTransactionUpdatedWebhookEvent,
+    CardTransactionEnhancedDataCreatedWebhookEvent,
+    CardTransactionEnhancedDataUpdatedWebhookEvent,
+    DigitalWalletTokenizationApprovalRequestWebhookEvent,
+    DigitalWalletTokenizationResultWebhookEvent,
+    DigitalWalletTokenizationTwoFactorAuthenticationCodeWebhookEvent,
+    DigitalWalletTokenizationTwoFactorAuthenticationCodeSentWebhookEvent,
+    DigitalWalletTokenizationUpdatedWebhookEvent,
+    DisputeUpdatedWebhookEvent,
+    DisputeEvidenceUploadFailedWebhookEvent,
+    ExternalBankAccountCreatedWebhookEvent,
+    ExternalBankAccountUpdatedWebhookEvent,
+    ExternalPaymentCreatedWebhookEvent,
+    ExternalPaymentUpdatedWebhookEvent,
+    FinancialAccountCreatedWebhookEvent,
+    FinancialAccountUpdatedWebhookEvent,
+    FundingEventCreatedWebhookEvent,
+    LoanTapeCreatedWebhookEvent,
+    LoanTapeUpdatedWebhookEvent,
+    ManagementOperationCreatedWebhookEvent,
+    ManagementOperationUpdatedWebhookEvent,
+    InternalTransactionCreatedWebhookEvent,
+    InternalTransactionUpdatedWebhookEvent,
+    NetworkTotalCreatedWebhookEvent,
+    NetworkTotalUpdatedWebhookEvent,
+    PaymentTransactionCreatedWebhookEvent,
+    PaymentTransactionUpdatedWebhookEvent,
+    SettlementReportUpdatedWebhookEvent,
+    StatementsCreatedWebhookEvent,
+    ThreeDSAuthenticationCreatedWebhookEvent,
+    ThreeDSAuthenticationUpdatedWebhookEvent,
+    ThreeDSAuthenticationChallengeWebhookEvent,
+    TokenizationApprovalRequestWebhookEvent,
+    TokenizationResultWebhookEvent,
+    TokenizationTwoFactorAuthenticationCodeWebhookEvent,
+    TokenizationTwoFactorAuthenticationCodeSentWebhookEvent,
+    TokenizationUpdatedWebhookEvent,
+    DisputeTransactionCreatedWebhookEvent,
+    DisputeTransactionUpdatedWebhookEvent,
+    AccountHolderCreatedWebhookEvent,
+    AccountHolderUpdatedWebhookEvent,
+    AccountHolderVerificationWebhookEvent,
+    AccountHolderDocumentUpdatedWebhookEvent,
+    AsaRequestWebhookEvent,
+    TokenizationDecisioningRequestWebhookEvent,
+    AuthRulesBacktestReportCreatedWebhookEvent,
+    BalanceUpdatedWebhookEvent,
+    BookTransferTransactionCreatedWebhookEvent,
+    BookTransferTransactionUpdatedWebhookEvent,
+    CardCreatedWebhookEvent,
+    CardConvertedWebhookEvent,
+    CardRenewedWebhookEvent,
+    CardReissuedWebhookEvent,
+    CardShippedWebhookEvent,
+    CardTransactionUpdatedWebhookEvent,
+    CardTransactionEnhancedDataCreatedWebhookEvent,
+    CardTransactionEnhancedDataUpdatedWebhookEvent,
+    DigitalWalletTokenizationApprovalRequestWebhookEvent,
+    DigitalWalletTokenizationResultWebhookEvent,
+    DigitalWalletTokenizationTwoFactorAuthenticationCodeWebhookEvent,
+    DigitalWalletTokenizationTwoFactorAuthenticationCodeSentWebhookEvent,
+    DigitalWalletTokenizationUpdatedWebhookEvent,
+    DisputeUpdatedWebhookEvent,
+    DisputeEvidenceUploadFailedWebhookEvent,
+    ExternalBankAccountCreatedWebhookEvent,
+    ExternalBankAccountUpdatedWebhookEvent,
+    ExternalPaymentCreatedWebhookEvent,
+    ExternalPaymentUpdatedWebhookEvent,
+    FinancialAccountCreatedWebhookEvent,
+    FinancialAccountUpdatedWebhookEvent,
+    FundingEventCreatedWebhookEvent,
+    LoanTapeCreatedWebhookEvent,
+    LoanTapeUpdatedWebhookEvent,
+    ManagementOperationCreatedWebhookEvent,
+    ManagementOperationUpdatedWebhookEvent,
+    InternalTransactionCreatedWebhookEvent,
+    InternalTransactionUpdatedWebhookEvent,
+    NetworkTotalCreatedWebhookEvent,
+    NetworkTotalUpdatedWebhookEvent,
+    PaymentTransactionCreatedWebhookEvent,
+    PaymentTransactionUpdatedWebhookEvent,
+    SettlementReportUpdatedWebhookEvent,
+    StatementsCreatedWebhookEvent,
+    ThreeDSAuthenticationCreatedWebhookEvent,
+    ThreeDSAuthenticationUpdatedWebhookEvent,
+    ThreeDSAuthenticationChallengeWebhookEvent,
+    TokenizationApprovalRequestWebhookEvent,
+    TokenizationResultWebhookEvent,
+    TokenizationTwoFactorAuthenticationCodeWebhookEvent,
+    TokenizationTwoFactorAuthenticationCodeSentWebhookEvent,
+    TokenizationUpdatedWebhookEvent,
+    DisputeTransactionCreatedWebhookEvent,
+    DisputeTransactionUpdatedWebhookEvent,
+    UnwrapTypedWebhookEvent,
+    UnwrapUnsafeWebhookEvent,
+)
+```

pyproject.toml

@@ -42,6 +42,7 @@ Repository = "https://github.com/lithic-com/lithic-python"
 
 [project.optional-dependencies]
 aiohttp = ["aiohttp", "httpx_aiohttp>=0.1.9"]
+webhooks = ["standardwebhooks"]
 
 [tool.rye]
 managed = true
@@ -59,6 +60,7 @@ dev-dependencies = [
     "importlib-metadata>=6.7.0",
     "rich>=13.7.1",
     "pytest-xdist>=3.6.1",
+    "standardwebhooks",
 ]
 
 [tool.rye.scripts]

requirements-dev.lock

@@ -29,6 +29,7 @@ async-timeout==5.0.1
 attrs==25.4.0
     # via aiohttp
     # via nox
+    # via standardwebhooks
 backports-asyncio-runner==1.2.0
     # via pytest-asyncio
 certifi==2025.11.12
@@ -38,6 +39,8 @@ colorlog==6.10.1
     # via nox
 dependency-groups==1.3.1
     # via nox
+deprecated==1.3.1
+    # via standardwebhooks
 dirty-equals==0.11
 distlib==0.4.0
     # via virtualenv
@@ -61,6 +64,7 @@ httpx==0.28.1
     # via httpx-aiohttp
     # via lithic
     # via respx
+    # via standardwebhooks
 httpx-aiohttp==0.1.9
     # via lithic
 humanize==4.13.0
@@ -112,6 +116,7 @@ pytest==8.4.2
 pytest-asyncio==1.2.0
 pytest-xdist==3.8.0
 python-dateutil==2.9.0.post0
+    # via standardwebhooks
     # via time-machine
 respx==0.22.0
 rich==14.2.0
@@ -120,12 +125,18 @@ six==1.17.0
     # via python-dateutil
 sniffio==1.3.1
     # via lithic
+standardwebhooks==1.0.0
+    # via lithic
 time-machine==2.19.0
 tomli==2.3.0
     # via dependency-groups
     # via mypy
     # via nox
     # via pytest
+types-deprecated==1.3.1.20251101
+    # via standardwebhooks
+types-python-dateutil==2.9.0.20251115
+    # via standardwebhooks
 typing-extensions==4.15.0
     # via aiosignal
     # via anyio
@@ -143,6 +154,8 @@ typing-inspection==0.4.2
     # via pydantic
 virtualenv==20.35.4
     # via nox
+wrapt==2.0.1
+    # via deprecated
 yarl==1.22.0
     # via aiohttp
 zipp==3.23.0

requirements.lock

@@ -26,9 +26,12 @@ async-timeout==5.0.1
     # via aiohttp
 attrs==25.4.0
     # via aiohttp
+    # via standardwebhooks
 certifi==2025.11.12
     # via httpcore
     # via httpx
+deprecated==1.3.1
+    # via standardwebhooks
 distro==1.9.0
     # via lithic
 exceptiongroup==1.3.1
@@ -43,6 +46,7 @@ httpcore==1.0.9
 httpx==0.28.1
     # via httpx-aiohttp
     # via lithic
+    # via standardwebhooks
 httpx-aiohttp==0.1.9
     # via lithic
 idna==3.11
@@ -59,8 +63,18 @@ pydantic==2.12.5
     # via lithic
 pydantic-core==2.41.5
     # via pydantic
+python-dateutil==2.9.0.post0
+    # via standardwebhooks
+six==1.17.0
+    # via python-dateutil
 sniffio==1.3.1
     # via lithic
+standardwebhooks==1.0.0
+    # via lithic
+types-deprecated==1.3.1.20251101
+    # via standardwebhooks
+types-python-dateutil==2.9.0.20251115
+    # via standardwebhooks
 typing-extensions==4.15.0
     # via aiosignal
     # via anyio
@@ -72,5 +86,7 @@ typing-extensions==4.15.0
     # via typing-inspection
 typing-inspection==0.4.2
     # via pydantic
+wrapt==2.0.1
+    # via deprecated
 yarl==1.22.0
     # via aiohttp

src/lithic/__init__.py

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

src/lithic/_client.py

@@ -74,6 +74,7 @@
     from .resources.balances import Balances, AsyncBalances
     from .resources.disputes import Disputes, AsyncDisputes
     from .resources.payments import Payments, AsyncPayments
+    from .resources.webhooks import Webhooks, AsyncWebhooks
     from .resources.cards.cards import Cards, AsyncCards
     from .resources.disputes_v2 import DisputesV2, AsyncDisputesV2
     from .resources.fraud.fraud import Fraud, AsyncFraud
@@ -392,6 +393,12 @@ def account_activity(self) -> AccountActivity:
 
         return AccountActivity(self)
 
+    @cached_property
+    def webhooks(self) -> Webhooks:
+        from .resources.webhooks import Webhooks
+
+        return Webhooks(self)
+
     @cached_property
     def with_raw_response(self) -> LithicWithRawResponse:
         return LithicWithRawResponse(self)

src/lithic/_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/lithic/resources/__init__.py

@@ -425,4 +425,6 @@
     "AsyncAccountActivityWithRawResponse",
     "AccountActivityWithStreamingResponse",
     "AsyncAccountActivityWithStreamingResponse",
+    "Webhooks",
+    "AsyncWebhooks",
 ]

src/lithic/resources/webhooks.py

@@ -1,3 +1,4 @@
+<<<<<<< HEAD
 # File generated from our OpenAPI spec by Stainless.
 
 from __future__ import annotations
@@ -205,3 +206,75 @@ def verify_signature(
                 return None
 
         raise ValueError("None of the given webhook signatures match the expected signature")
+||||||| parent of 49e654d (feat(api): add webhook schemas to SDKs - add parse and parse_unsafe)
+=======
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+import json
+from typing import Mapping, cast
+
+from .._models import construct_type
+from .._resource import SyncAPIResource, AsyncAPIResource
+from .._exceptions import LithicError
+from ..types.parsed_webhook_event import ParsedWebhookEvent
+
+__all__ = ["Webhooks", "AsyncWebhooks"]
+
+
+class Webhooks(SyncAPIResource):
+    def parsed(self, payload: str, *, headers: Mapping[str, str], key: str | bytes | None = None) -> ParsedWebhookEvent:
+        try:
+            from standardwebhooks import Webhook
+        except ImportError as exc:
+            raise LithicError("You need to install `lithic[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(
+            ParsedWebhookEvent,
+            construct_type(
+                type_=ParsedWebhookEvent,
+                value=json.loads(payload),
+            ),
+        )
+
+
+class AsyncWebhooks(AsyncAPIResource):
+    def parsed(self, payload: str, *, headers: Mapping[str, str], key: str | bytes | None = None) -> ParsedWebhookEvent:
+        try:
+            from standardwebhooks import Webhook
+        except ImportError as exc:
+            raise LithicError("You need to install `lithic[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(
+            ParsedWebhookEvent,
+            construct_type(
+                type_=ParsedWebhookEvent,
+                value=json.loads(payload),
+            ),
+        )
+>>>>>>> 49e654d (feat(api): add webhook schemas to SDKs - add parse and parse_unsafe)