INTER-2061: Document webhook types, commit conventions, and codegen update process

README.md

@@ -37,6 +37,11 @@ The following versions of Java are supported
 - Java 21
 - Java 25
 
+We aim to support all Java LTS versions that are still maintained upstream.
+
+> [!NOTE]
+> This package assumes you have a Fingerprint subscription or trial, it is not compatible with the [open-source FingerprintJS](https://github.com/fingerprintjs/fingerprintjs). See our documentation to learn more about the [differences between Fingerprint and the open-source FingerprintJS](https://fingerprint.com/github/).
+
 ## Installation
 
 ### Maven users
@@ -223,7 +228,21 @@ public class SealedResults {
 ```
 To learn more, see the [Sealed results example](/examples/src/main/java/com/fingerprint/example/SealedResults.java).
 
-## Webhook signature validation
+## Webhooks
+
+### Webhook types
+
+A [webhook](https://dev.fingerprint.com/reference/posteventwebhook) sent by Fingerprint has the same shape as an `Event`. You can deserialize the payload directly into that type using the SDK's own JSON mapper:
+
+```java
+import com.fingerprint.v4.model.Event;
+import com.fingerprint.v4.sdk.JSON;
+
+Event event = JSON.getDefault().getMapper().readValue(webhook, Event.class);
+System.out.println(event.getIdentification().getVisitorId());
+```
+
+### Webhook signature validation
 This SDK provides utility method for verifying the HMAC signature of the incoming webhook request.
 
 Here is an example implementation using Spring Boot:

contributing.md

@@ -8,6 +8,16 @@ Most files in the project are autogenerated by [openapi-generator](https://opena
 - [docs](./docs) - generated documentation for models and [API Client](./docs/FingerprintApi.md).
 - [sdk](./sdk) - automatically generated API client code.
 
+## Commit messages
+
+This project follows the [Conventional Commits](https://www.conventionalcommits.org/) standard. Each commit message should be structured as:
+
+```
+<type>: <description>
+
+[optional body]
+```
+
 ## Code generation and building the SDK
 
 Use the Gradle build to invoke `openapi-generator` and generate the code and documentation:
@@ -18,6 +28,14 @@ Use the Gradle build to invoke `openapi-generator` and generate the code and doc
 
 To download the latest OpenAPI schema from [fingerprintjs/fingerprint-pro-server-api-openapi](https://github.com/fingerprintjs/fingerprint-pro-server-api-openapi), run `./scripts/sync.sh`
 
+### Updating the codegen engine and templates
+
+The generator version is pinned as the `openapi` entry in [gradle/libs.versions.toml](./gradle/libs.versions.toml). To update it:
+
+1. Bump the `openapi` version in that file.
+2. Compare each file in [template](./template) against the matching upstream `java` or `jersey3` generator template at the new version, and merge in any upstream changes the same way you would resolve a merge conflict.
+3. Update the engine and the templates in the same change. Using the new engine with old templates, or the other way around, can break code generation without a clear error.
+
 ## Testing the local source code of the SDK
 
 Use the [./src/examples/java/com/fingerprint/example/FunctionalTests.java](./src/examples/java/com/fingerprint/example/FunctionalTests.java) file to make API requests using the local version of the SDK.

template/README.mustache

@@ -37,6 +37,11 @@ The following versions of Java are supported
 - Java 21
 - Java 25
 
+We aim to support all Java LTS versions that are still maintained upstream.
+
+> [!NOTE]
+> This package assumes you have a Fingerprint subscription or trial, it is not compatible with the [open-source FingerprintJS](https://github.com/fingerprintjs/fingerprintjs). See our documentation to learn more about the [differences between Fingerprint and the open-source FingerprintJS](https://fingerprint.com/github/).
+
 ## Installation
 
 ### Maven users
@@ -223,7 +228,21 @@ public class SealedResults {
 ```
 To learn more, see the [Sealed results example](/examples/src/main/java/com/fingerprint/example/SealedResults.java).
 
-## Webhook signature validation
+## Webhooks
+
+### Webhook types
+
+A [webhook](https://dev.fingerprint.com/reference/posteventwebhook) sent by Fingerprint has the same shape as an `Event`. You can deserialize the payload directly into that type using the SDK's own JSON mapper:
+
+```java
+import com.fingerprint.v4.model.Event;
+import com.fingerprint.v4.sdk.JSON;
+
+Event event = JSON.getDefault().getMapper().readValue(webhook, Event.class);
+System.out.println(event.getIdentification().getVisitorId());
+```
+
+### Webhook signature validation
 This SDK provides utility method for verifying the HMAC signature of the incoming webhook request.
 
 Here is an example implementation using Spring Boot: