feat(api): add parse/parseUnsafe webhook helpers and event schemas

Author: mirek26

README.md

@@ -354,15 +354,50 @@ Or to `debug` for more verbose logging:
 export LITHIC_LOG=debug
 ```
 
-## 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 SDK provides methods for verifying webhook signatures and parsing event payloads.
 
-You can use `lithic.webhooks().verifySignature(body, headers, secret?)` or `lithic.webhooks().unwrap(body, headers, secret?)`,
-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.
+Use `parse()` to verify the signature and return a typed event:
+
+```java
+import com.lithic.api.core.http.Headers;
+import com.lithic.api.models.ParsedWebhookEvent;
+
+// Convert request headers to Headers object
+Headers headers = Headers.builder().putAll(request.getHeaders()).build();
+
+// Verify signature and parse payload
+// Secret is optional if configured on client or set via LITHIC_WEBHOOK_SECRET env var
+ParsedWebhookEvent event = client.webhooks().parse(requestBody, headers, null);
+
+// Handle based on event type using isXxx() checks
+if (event.isCardCreated()) {
+    System.out.println("Card created: " + event.asCardCreated().cardToken());
+} else if (event.isCardTransactionUpdated()) {
+    String transactionToken = event.asCardTransactionUpdated().token();
+    System.out.println("Transaction updated: " + transactionToken);
+}
+
+```
+
+### Parsing without verification
+You can parse the webhook body without verifying the signature using `parseUnsafe()`. This is not recommended for production use:
+
+```
+// Parse only - skips signature verification (not recommended for production)
+ParsedWebhookEvent event = client.webhooks().parseUnsafe(body);
+```
+
+### Manual signature verification
+To verify the signature without parsing the body, use `verifySignature()`:
+
+```
+// Only verify signature, don't parse. Throws LithicException if signature is invalid
+client.webhooks().verifySignature(body, headers, null);
+```
 
 ## ProGuard and R8
 

lithic-java-core/src/main/kotlin/com/lithic/api/client/LithicClient.kt

@@ -113,8 +113,6 @@ interface LithicClient {
 
     fun responderEndpoints(): ResponderEndpointService
 
-    fun webhooks(): WebhookService
-
     fun externalBankAccounts(): ExternalBankAccountService
 
     fun payments(): PaymentService
@@ -145,6 +143,8 @@ interface LithicClient {
 
     fun accountActivity(): AccountActivityService
 
+    fun webhooks(): WebhookService
+
     /** Status of api */
     fun apiStatus(): ApiStatus = apiStatus(ClientApiStatusParams.none())
 
@@ -249,6 +249,8 @@ interface LithicClient {
 
         fun accountActivity(): AccountActivityService.WithRawResponse
 
+        fun webhooks(): WebhookService.WithRawResponse
+
         /**
          * Returns a raw HTTP response for `get /v1/status`, but is otherwise the same as
          * [LithicClient.apiStatus].

lithic-java-core/src/main/kotlin/com/lithic/api/client/LithicClientAsync.kt

@@ -113,8 +113,6 @@ interface LithicClientAsync {
 
     fun responderEndpoints(): ResponderEndpointServiceAsync
 
-    fun webhooks(): WebhookServiceAsync
-
     fun externalBankAccounts(): ExternalBankAccountServiceAsync
 
     fun payments(): PaymentServiceAsync
@@ -145,6 +143,8 @@ interface LithicClientAsync {
 
     fun accountActivity(): AccountActivityServiceAsync
 
+    fun webhooks(): WebhookServiceAsync
+
     /** Status of api */
     fun apiStatus(): CompletableFuture<ApiStatus> = apiStatus(ClientApiStatusParams.none())
 
@@ -252,6 +252,8 @@ interface LithicClientAsync {
 
         fun accountActivity(): AccountActivityServiceAsync.WithRawResponse
 
+        fun webhooks(): WebhookServiceAsync.WithRawResponse
+
         /**
          * Returns a raw HTTP response for `get /v1/status`, but is otherwise the same as
          * [LithicClientAsync.apiStatus].

lithic-java-core/src/main/kotlin/com/lithic/api/client/LithicClientAsyncImpl.kt

@@ -169,8 +169,6 @@ class LithicClientAsyncImpl(private val clientOptions: ClientOptions) : LithicCl
         ResponderEndpointServiceAsyncImpl(clientOptionsWithUserAgent)
     }
 
-    private val webhooks: WebhookServiceAsync by lazy { WebhookServiceAsyncImpl(clientOptions) }
-
     private val externalBankAccounts: ExternalBankAccountServiceAsync by lazy {
         ExternalBankAccountServiceAsyncImpl(clientOptionsWithUserAgent)
     }
@@ -231,6 +229,10 @@ class LithicClientAsyncImpl(private val clientOptions: ClientOptions) : LithicCl
         AccountActivityServiceAsyncImpl(clientOptionsWithUserAgent)
     }
 
+    private val webhooks: WebhookServiceAsync by lazy {
+        WebhookServiceAsyncImpl(clientOptionsWithUserAgent)
+    }
+
     override fun sync(): LithicClient = sync
 
     override fun withRawResponse(): LithicClientAsync.WithRawResponse = withRawResponse
@@ -273,8 +275,6 @@ class LithicClientAsyncImpl(private val clientOptions: ClientOptions) : LithicCl
 
     override fun responderEndpoints(): ResponderEndpointServiceAsync = responderEndpoints
 
-    override fun webhooks(): WebhookServiceAsync = webhooks
-
     override fun externalBankAccounts(): ExternalBankAccountServiceAsync = externalBankAccounts
 
     override fun payments(): PaymentServiceAsync = payments
@@ -305,6 +305,8 @@ class LithicClientAsyncImpl(private val clientOptions: ClientOptions) : LithicCl
 
     override fun accountActivity(): AccountActivityServiceAsync = accountActivity
 
+    override fun webhooks(): WebhookServiceAsync = webhooks
+
     override fun apiStatus(
         params: ClientApiStatusParams,
         requestOptions: RequestOptions,
@@ -449,6 +451,10 @@ class LithicClientAsyncImpl(private val clientOptions: ClientOptions) : LithicCl
             AccountActivityServiceAsyncImpl.WithRawResponseImpl(clientOptions)
         }
 
+        private val webhooks: WebhookServiceAsync.WithRawResponse by lazy {
+            WebhookServiceAsyncImpl.WithRawResponseImpl(clientOptions)
+        }
+
         override fun withOptions(
             modifier: Consumer<ClientOptions.Builder>
         ): LithicClientAsync.WithRawResponse =
@@ -530,6 +536,8 @@ class LithicClientAsyncImpl(private val clientOptions: ClientOptions) : LithicCl
         override fun accountActivity(): AccountActivityServiceAsync.WithRawResponse =
             accountActivity
 
+        override fun webhooks(): WebhookServiceAsync.WithRawResponse = webhooks
+
         private val apiStatusHandler: Handler<ApiStatus> =
             jsonHandler<ApiStatus>(clientOptions.jsonMapper)
 

lithic-java-core/src/main/kotlin/com/lithic/api/client/LithicClientImpl.kt

@@ -160,8 +160,6 @@ class LithicClientImpl(private val clientOptions: ClientOptions) : LithicClient
         ResponderEndpointServiceImpl(clientOptionsWithUserAgent)
     }
 
-    private val webhooks: WebhookService by lazy { WebhookServiceImpl(clientOptions) }
-
     private val externalBankAccounts: ExternalBankAccountService by lazy {
         ExternalBankAccountServiceImpl(clientOptionsWithUserAgent)
     }
@@ -214,6 +212,8 @@ class LithicClientImpl(private val clientOptions: ClientOptions) : LithicClient
         AccountActivityServiceImpl(clientOptionsWithUserAgent)
     }
 
+    private val webhooks: WebhookService by lazy { WebhookServiceImpl(clientOptionsWithUserAgent) }
+
     override fun async(): LithicClientAsync = async
 
     override fun withRawResponse(): LithicClient.WithRawResponse = withRawResponse
@@ -255,8 +255,6 @@ class LithicClientImpl(private val clientOptions: ClientOptions) : LithicClient
 
     override fun responderEndpoints(): ResponderEndpointService = responderEndpoints
 
-    override fun webhooks(): WebhookService = webhooks
-
     override fun externalBankAccounts(): ExternalBankAccountService = externalBankAccounts
 
     override fun payments(): PaymentService = payments
@@ -287,6 +285,8 @@ class LithicClientImpl(private val clientOptions: ClientOptions) : LithicClient
 
     override fun accountActivity(): AccountActivityService = accountActivity
 
+    override fun webhooks(): WebhookService = webhooks
+
     override fun apiStatus(
         params: ClientApiStatusParams,
         requestOptions: RequestOptions,
@@ -431,6 +431,10 @@ class LithicClientImpl(private val clientOptions: ClientOptions) : LithicClient
             AccountActivityServiceImpl.WithRawResponseImpl(clientOptions)
         }
 
+        private val webhooks: WebhookService.WithRawResponse by lazy {
+            WebhookServiceImpl.WithRawResponseImpl(clientOptions)
+        }
+
         override fun withOptions(
             modifier: Consumer<ClientOptions.Builder>
         ): LithicClient.WithRawResponse =
@@ -510,6 +514,8 @@ class LithicClientImpl(private val clientOptions: ClientOptions) : LithicClient
 
         override fun accountActivity(): AccountActivityService.WithRawResponse = accountActivity
 
+        override fun webhooks(): WebhookService.WithRawResponse = webhooks
+
         private val apiStatusHandler: Handler<ApiStatus> =
             jsonHandler<ApiStatus>(clientOptions.jsonMapper)