feat: createCallback implementation and asyncTest setup

* feat: initial callback design

* feat: implemented callback with serdes and samples

* Added Callback Serdes

* Simplified Callback Tests

* Implemented Cloud based testing for callback

* Finalize tests

* removed temp design

* Adapted readme

* Adding serdes to config

* Adapted readme

* Review comments and formatting

* add a method to construct TypeToken from Class (#19)

* add a method to construct TypeToken from Class

* remove resultType from StepOperation

* fix tests and examples

* revert the accidental changes made by IntelliJ

* feat(error-handling): Support specific type error reconstruction from… (#15)

* feat: implemented callback with serdes and samples

* Implemented Cloud based testing for callback

* Formatting

* Review fixes and simplifications

* Review fixes and simplifications

* Review comments

* Fixed branches for testing

* History Event Process - fix missing cases

* Review fixes and simplifications

---------

Co-authored-by: Frank Chen <65260095+zhongkechen@users.noreply.github.com>
Co-authored-by: Philipp Page <pagejep@amazon.com>

Author: 3 people

AGENTS.md

@@ -28,6 +28,9 @@ mvn test -Dtest=DurableContextTest
 
 # Skip tests
 mvn install -DskipTests
+
+# Format code (ALWAYS run after making changes)
+mvn spotless:apply
 ```
 
 ## Key Directories
@@ -64,7 +67,11 @@ import static org.junit.jupiter.api.Assertions.*;           // Tests
 import static java.util.Collections.emptyList;              // Factory methods
 import static com.amazonaws.lambda.durable.model.Status.*;  // Enums
 
-// AVOID fully qualified names in code
+// ALWAYS use proper imports, NEVER use fully qualified class names in code
+// Bad:  var lambda = software.amazon.awssdk.services.lambda.LambdaClient.create();
+// Good: import software.amazon.awssdk.services.lambda.LambdaClient;
+//       var lambda = LambdaClient.create();
+
 // Bad:  com.amazonaws.lambda.durable.model.Status.SUCCESS
 // Good: import static and use SUCCESS directly
 
@@ -232,6 +239,10 @@ Check `ExecutionManager` for thread registration and coordination logic if debug
 - Check existing code for patterns (especially in `operation/` package)
 - Prefer minimal changes over large refactors
 
+## After Making Changes
+
+**ALWAYS run `mvn spotless:apply` after making code changes** to ensure consistent formatting across the codebase. This applies code formatting rules automatically.
+
 ## Further Reading
 
 ### Official AWS SDKs

README.md

@@ -20,6 +20,7 @@ Your durable function extends `DurableHandler<I, O>` and implements `handleReque
 - `ctx.step()` – Execute code and checkpoint the result
 - `ctx.stepAsync()` – Start concurrent operations  
 - `ctx.wait()` – Suspend execution without compute charges
+- `ctx.createCallback()` – Wait for external events (approvals, webhooks)
 
 ## Quick Start
 
@@ -110,6 +111,63 @@ ctx.wait(Duration.ofMinutes(30));
 ctx.wait("cooling-off-period", Duration.ofDays(7));
 ```
 
+### createCallback() – Wait for External Events
+
+Callbacks suspend execution until an external system sends a result. Use this for human approvals, webhooks, or any event-driven workflow.
+
+```java
+// Create a callback and get the ID to share with external systems
+DurableCallbackFuture<String> callback = ctx.createCallback("approval", String.class);
+
+// Send the callback ID to an external system within a step
+ctx.step("send-notification", String.class, () -> {
+    notificationService.sendApprovalRequest(callback.callbackId(), requestDetails);
+    return "notification-sent";
+});
+
+// Suspend until the external system calls back with a result
+String approvalResult = callback.get();
+```
+
+The external system completes the callback by calling the Lambda Durable Functions API with the callback ID and result payload.
+
+#### Callback Configuration
+
+Configure timeouts and serialization to handle cases where callbacks are never completed or need custom deserialization:
+
+```java
+var config = CallbackConfig.builder()
+    .timeout(Duration.ofHours(24))        // Max time to wait for callback
+    .heartbeatTimeout(Duration.ofHours(1)) // Max time between heartbeats
+    .serDes(new CustomSerDes())           // Custom serialization/deserialization
+    .build();
+
+var callback = ctx.createCallback("approval", String.class, config);
+```
+
+| Option | Description |
+|--------|-------------|
+| `timeout()` | Maximum duration to wait for the callback to complete |
+| `heartbeatTimeout()` | Maximum duration between heartbeat signals from the external system |
+| `serDes()` | Custom SerDes for deserializing callback results (e.g., encryption, custom formats) |
+
+#### Callback Exceptions
+
+| Exception | When Thrown |
+|-----------|-------------|
+| `CallbackTimeoutException` | Callback exceeded its timeout duration |
+| `CallbackFailedException` | External system sent an error response |
+
+```java
+try {
+    var result = callback.get();
+} catch (CallbackTimeoutException e) {
+    // Callback timed out - implement fallback logic
+} catch (CallbackFailedException e) {
+    // External system reported an error
+}
+```
+
 ## Step Configuration
 
 Configure step behavior with `StepConfig`:
@@ -307,6 +365,8 @@ The SDK throws specific exceptions to help you handle different failure scenario
 |-----------|-------------|---------------|
 | `StepFailedException` | Step exhausted all retry attempts | Catch to implement fallback logic or let execution fail |
 | `StepInterruptedException` | `AT_MOST_ONCE` step was interrupted before completion | Implement manual recovery (check if operation completed externally) |
+| `CallbackTimeoutException` | Callback exceeded its timeout duration | Implement fallback logic or escalation |
+| `CallbackFailedException` | External system sent an error response to the callback | Handle the error or propagate failure |
 | `NonDeterministicExecutionException` | Code changed between original execution and replay | Fix code to maintain determinism; don't change step order/names |
 
 ```java

examples/src/main/java/com/amazonaws/lambda/durable/examples/CallbackExample.java

@@ -0,0 +1,78 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package com.amazonaws.lambda.durable.examples;
+
+import com.amazonaws.lambda.durable.CallbackConfig;
+import com.amazonaws.lambda.durable.DurableContext;
+import com.amazonaws.lambda.durable.DurableHandler;
+import java.time.Duration;
+
+/**
+ * Example demonstrating callback operations for external system integration.
+ *
+ * <p>This handler demonstrates a human approval workflow:
+ *
+ * <ol>
+ *   <li>Prepare the request for approval
+ *   <li>Create a callback and send the callback ID to an external approval system
+ *   <li>Suspend execution until the external system responds
+ *   <li>Process the approval result
+ * </ol>
+ *
+ * <p>External systems respond using AWS Lambda APIs:
+ *
+ * <ul>
+ *   <li>{@code SendDurableExecutionCallbackSuccess} - approve with result
+ *   <li>{@code SendDurableExecutionCallbackFailure} - reject with error
+ *   <li>{@code SendDurableExecutionCallbackHeartbeat} - keep callback alive
+ * </ul>
+ */
+public class CallbackExample extends DurableHandler<ApprovalRequest, String> {
+
+    @Override
+    public String handleRequest(ApprovalRequest input, DurableContext context) {
+        // Step 1: Prepare the approval request
+        var prepared = context.step(
+                "prepare",
+                String.class,
+                () -> "Approval request for: " + input.description() + " ($" + input.amount() + ")");
+
+        // Step 2: Create callback for external approval
+        // Use timeout from input if provided, otherwise default to 5 minutes
+        var timeout =
+                input.timeoutSeconds() != null ? Duration.ofSeconds(input.timeoutSeconds()) : Duration.ofMinutes(5);
+
+        var config = CallbackConfig.builder().timeout(timeout).build();
+
+        var callback = context.createCallback("approval", String.class, config);
+
+        // Step 2.5: Log AWS CLI command to complete the callback
+        context.step("log-callback-command", Void.class, () -> {
+            var callbackId = callback.callbackId();
+            // The result must be base64-encoded JSON
+            var command = String.format(
+                    "aws lambda send-durable-execution-callback-success --callback-id %s --result $(echo -n '\"approved\"' | base64)",
+                    callbackId);
+            context.getLogger().info("To complete this callback, run: {}", command);
+            return null;
+        });
+
+        // Step 3: Wait for external approval (suspends execution)
+        var approvalResult = callback.get();
+
+        // Step 4: Process the approval
+        var result = context.step("process-approval", String.class, () -> {
+            return prepared + " - " + approvalResult;
+        });
+
+        return result;
+    }
+}
+
+/** Input for the approval workflow. */
+record ApprovalRequest(String description, double amount, Integer timeoutSeconds) {
+    // Convenience constructor for default timeout
+    public ApprovalRequest(String description, double amount) {
+        this(description, amount, null);
+    }
+}

examples/src/test/java/com/amazonaws/lambda/durable/examples/CallbackExampleTest.java

@@ -0,0 +1,56 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+package com.amazonaws.lambda.durable.examples;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import com.amazonaws.lambda.durable.model.ExecutionStatus;
+import com.amazonaws.lambda.durable.testing.LocalDurableTestRunner;
+import org.junit.jupiter.api.Test;
+import software.amazon.awssdk.services.lambda.model.OperationStatus;
+import software.amazon.awssdk.services.lambda.model.OperationType;
+
+class CallbackExampleTest {
+
+    @Test
+    void testCallbackExampleSuspendsForApproval() {
+        var handler = new CallbackExample();
+        var runner = LocalDurableTestRunner.create(ApprovalRequest.class, handler);
+
+        var input = new ApprovalRequest("New laptop", 1500.00);
+
+        // First run - prepares request and creates callback, then suspends
+        var result = runner.run(input);
+
+        assertEquals(ExecutionStatus.PENDING, result.getStatus());
+
+        // Verify the callback was created
+        var callbackOp = runner.getOperation("approval");
+        assertNotNull(callbackOp);
+        assertEquals(OperationType.CALLBACK, callbackOp.getType());
+        assertEquals(OperationStatus.STARTED, callbackOp.getStatus());
+    }
+
+    @Test
+    void testCallbackExampleCompletesAfterApproval() {
+        var handler = new CallbackExample();
+        var runner = LocalDurableTestRunner.create(ApprovalRequest.class, handler);
+
+        var input = new ApprovalRequest("New laptop", 1500.00);
+
+        // First run - suspends waiting for callback
+        var result = runner.run(input);
+        assertEquals(ExecutionStatus.PENDING, result.getStatus());
+
+        // Simulate external system approving the request
+        var callbackId = runner.getCallbackId("approval");
+        runner.completeCallback(callbackId, "\"Approved by manager\"");
+
+        // Second run - callback complete, finishes processing
+        result = runner.run(input);
+
+        assertEquals(ExecutionStatus.SUCCEEDED, result.getStatus());
+        assertEquals(
+                "Approval request for: New laptop ($1500.0) - Approved by manager", result.getResult(String.class));
+    }
+}

examples/src/test/java/com/amazonaws/lambda/durable/examples/CloudBasedIntegrationTest.java

@@ -11,10 +11,13 @@
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.condition.EnabledIf;
 import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
+import software.amazon.awssdk.core.SdkBytes;
+import software.amazon.awssdk.services.lambda.LambdaClient;
+import software.amazon.awssdk.services.lambda.model.OperationStatus;
 import software.amazon.awssdk.services.sts.StsClient;
 
 @EnabledIf("isEnabled")
-public class CloudBasedIntegrationTest {
+class CloudBasedIntegrationTest {
 
     private static String account;
     private static String region;
@@ -237,4 +240,96 @@ void testErrorHandlingExample() {
         assertTrue(finalResult.contains("fallback-result"));
         assertTrue(finalResult.contains("payment-"));
     }
+
+    @Test
+    void testCallbackExample() throws Exception {
+        var runner = CloudDurableTestRunner.create(arn("callback-example"), ApprovalRequest.class, String.class);
+
+        // Start async execution
+        var execution = runner.startAsync(new ApprovalRequest("Purchase order", 5000.0));
+
+        // Wait for callback to appear
+        execution.pollUntil(exec -> exec.hasCallback("approval"));
+
+        // Get callback ID
+        var callbackId = execution.getCallbackId("approval");
+        assertNotNull(callbackId);
+
+        // Complete the callback using AWS SDK
+        var lambda = LambdaClient.create();
+        lambda.sendDurableExecutionCallbackSuccess(
+                req -> req.callbackId(callbackId).result(SdkBytes.fromUtf8String("\"approved\"")));
+
+        // Wait for execution to complete
+        var result = execution.pollUntilComplete();
+        assertEquals(ExecutionStatus.SUCCEEDED, result.getStatus());
+
+        var finalResult = result.getResult(String.class);
+        assertNotNull(finalResult);
+        assertTrue(finalResult.contains("Approval request for: Purchase order"));
+        assertTrue(finalResult.contains("5000"));
+        assertTrue(finalResult.contains("approved"));
+
+        // Verify all operations completed
+        assertNotNull(execution.getOperation("prepare"));
+        assertNotNull(execution.getOperation("log-callback-command"));
+        assertNotNull(execution.getOperation("process-approval"));
+    }
+
+    @Test
+    void testCallbackExampleWithFailure() {
+        var runner = CloudDurableTestRunner.create(arn("callback-example"), ApprovalRequest.class, String.class);
+
+        // Start async execution
+        var execution = runner.startAsync(new ApprovalRequest("Purchase order", 5000.0));
+
+        // Wait for callback to appear
+        execution.pollUntil(exec -> exec.hasCallback("approval"));
+
+        // Get callback ID
+        var callbackId = execution.getCallbackId("approval");
+        assertNotNull(callbackId);
+
+        // Fail the callback using AWS SDK
+        var lambda = LambdaClient.create();
+        lambda.sendDurableExecutionCallbackFailure(req -> req.callbackId(callbackId)
+                .error(err -> err.errorType("ApprovalRejected").errorMessage("Approval rejected by manager")));
+
+        // Wait for execution to complete
+        var result = execution.pollUntilComplete();
+        assertEquals(ExecutionStatus.FAILED, result.getStatus());
+
+        // Verify the callback operation shows failure
+        var approvalOp = execution.getOperation("approval");
+        assertNotNull(approvalOp);
+        var callbackDetails = approvalOp.getCallbackDetails();
+        assertNotNull(callbackDetails);
+        assertNotNull(callbackDetails.error());
+        // Error message is redacted in the response, just verify error exists
+        assertTrue(callbackDetails.error().toString().contains("ErrorObject"));
+    }
+
+    @Test
+    void testCallbackExampleWithTimeout() {
+        var runner = CloudDurableTestRunner.create(arn("callback-example"), ApprovalRequest.class, String.class);
+
+        // Start async execution with 10 second timeout
+        var execution = runner.startAsync(new ApprovalRequest("Purchase order", 5000.0, 10));
+
+        // Wait for callback to appear
+        execution.pollUntil(exec -> exec.hasCallback("approval"));
+
+        // Get callback ID but don't complete it - let it timeout
+        var callbackId = execution.getCallbackId("approval");
+        assertNotNull(callbackId);
+
+        // Wait for execution to complete (should timeout after 10 seconds)
+        var result = execution.pollUntilComplete();
+        assertEquals(ExecutionStatus.FAILED, result.getStatus());
+
+        // Verify the callback operation shows timeout status
+        var approvalOp = execution.getOperation("approval");
+        assertNotNull(approvalOp);
+        assertEquals(OperationStatus.TIMED_OUT, approvalOp.getStatus());
+    }
 }