diff --git a/docs/develop/java/message-passing.mdx b/docs/develop/java/message-passing.mdx
index 4b9fe1b699..dc1f3c112d 100644
--- a/docs/develop/java/message-passing.mdx
+++ b/docs/develop/java/message-passing.mdx
@@ -506,6 +506,57 @@ public interface MyWorkflow {
 
 See [Finishing handlers before the Workflow completes](/encyclopedia/workflow-message-passing#finishing-message-handlers) for more information.
 
+### Use `@WorkflowInit` to operate on Workflow input before any handler executes
+
+Normally, your Workflows constructor won't have any parameters.
+However, if you use the `@WorkflowInit` annotation on your constructor, you can give it the same [Workflow parameters](/develop/java/core-application#workflow-parameters) as your `@WorkflowMethod`.
+The SDK will then ensure that your constructor receives the Workflow input arguments that the [Client sent](/develop/python/temporal-clients#start-workflow-execution).
+The Workflow input arguments are also passed to your `@WorkflowMethod` method -- that always happens, whether or not you use the `@WorkflowInit` annotation.
+This is useful if you have message handlers that need access to Workflow input: see [Initializing the Workflow first](/encyclopedia/workflow-message-passing#workflow-initializers).
+
+Here's an example.
+Notice that the constructor and `getGreeting` must have the same parameters:
+
+```java
+public class GreetingExample {
+    @WorkflowInterface
+    public interface GreetingWorkflow {
+        @WorkflowMethod
+        String getGreeting(String input);
+
+        @UpdateMethod
+        boolean checkTitleValidity();
+    }
+
+    public static class GreetingWorkflowImpl implements GreetingWorkflow {
+        private final String nameWithTitle;
+        private final String titleHasBeenChecked;
+        ...
+        // Note the annotation is on a public constructor
+        @WorkflowInit
+        public GreetingWorkflowImpl(String input) {
+          this.nameWithTitle = "Sir " + input;
+          this.titleHasBeenChecked = false;
+        }
+
+        @Override
+        public String getGreeting(String input) {
+          Workflow.await(() -> titleHasBeenChecked)
+          return "Hello " + nameWithTitle;
+        }
+
+        @Override
+        public boolean checkTitleValidity() {
+          // 👉 The handler is now guaranteed to see the workflow input
+          // after it has been processed by the constructor.
+          boolean isValid = activity.checkTitleValidity(nameWithTitle);
+          titleHasBeenChecked = true;
+          return isValid;
+        }
+    }
+}
+```
+
 ### Use locks to prevent concurrent handler execution {#control-handler-concurrency}
 
 Concurrent processes can interact in unpredictable ways.