fix(api): fix webhook parsing logic

Author: mirek26

README.md

@@ -200,27 +200,47 @@ card = client.cards.create(
 )
 ```
 
-## Webhook Verification
+## Webhooks
 
-We provide helper methods for verifying that a webhook request came from Lithic, and not a malicious third party.
+Lithic uses webhooks to notify your application when events happen. The library provides signature verification via the optional `standardwebhooks` package.
 
-You can use `lithic.webhooks.verify_signature(body: string, headers, secret?) -> None` or `lithic.webhooks.unwrap(body: string, headers, secret?) -> Payload`,
-both of which will raise an error if the signature is invalid.
+### Parsing and verifying webhooks
 
-Note that the "body" parameter must be the raw JSON string sent from the server (do not parse it first).
-The `.unwrap()` method can parse this JSON for you into a `Payload` object.
+```py
+from lithic.types import CardCreatedWebhookEvent
+
+# Verifies signature and returns typed event
+event = client.webhooks.parse(
+    request.body,  # raw request body as string
+    headers=request.headers,
+    secret=os.environ["LITHIC_WEBHOOK_SECRET"]  # optional, reads from env by default
+)
+
+# Use isinstance to narrow the type
+if isinstance(event, CardCreatedWebhookEvent):
+    print(f"Card created: {event.card_token}")
+```
+
+### Parsing without verification
+
+```py
+# Parse only - skips signature verification (not recommended for production)
+event = client.webhooks.parse_unsafe(request.body)
+```
 
-For example, in [FastAPI](https://fastapi.tiangolo.com/):
+### Verifying signatures only
 
 ```py
-@app.post('/my-webhook-handler')
-async def handler(request: Request):
-    body = await request.body()
-    secret = os.environ['LITHIC_WEBHOOK_SECRET']  # env var used by default; explicit here.
-    payload = client.webhooks.unwrap(body, request.headers, secret)
-    print(payload)
-
-    return {'ok': True}
+# Verify signature without parsing (raises exception if invalid)
+client.webhooks.verify_signature(request.body, headers=request.headers, secret=secret)
+```
+
+### Installing standardwebhooks (optional)
+
+To use signature verification, install the webhooks extra:
+
+```sh
+pip install lithic[webhooks]
 ```
 
 ## Handling errors

api.md

@@ -522,6 +522,8 @@ Methods:
 
 - <code>client.webhooks.<a href="./src/lithic/resources/webhooks.py">unwrap</a>(\*args) -> object</code>
 - <code>client.webhooks.<a href="./src/lithic/resources/webhooks.py">verify_signature</a>(\*args) -> None</code>
+- <code>client.webhooks.<a href="./src/lithic/resources/webhooks.py">parse</a>(body, headers, secret) -> ParsedWebhookEvent</code>
+- <code>client.webhooks.<a href="./src/lithic/resources/webhooks.py">parse_unsafe</a>(body) -> ParsedWebhookEvent</code>
 
 # ExternalBankAccounts
 
@@ -881,61 +883,6 @@ from lithic.types import (
     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,
+    ParsedWebhookEvent,
 )
 ```