feat: add webhooks and callbacks support (#147)

This PR adds webhooks and callbacks support to the Java SDK by implementing HMAC-based signature verification functionality. This enables secure event-driven integration with external systems through standardized webhook and callback mechanisms.

Key changes:
- Implemented HMAC signature verification system with configurable algorithms and encoding
- Added digest codec factory supporting multiple encoding formats (Hex, Base64, Base64Url)
- Comprehensive test suite covering various scenarios and edge cases

Author: haseeb-mhr

README.md

@@ -75,6 +75,8 @@ Core lib's Maven group ID is `io.apimatic`, and its artifact ID is `core`.
 | [`TestHelper`](./src/main/java/io/apimatic/core/utilities/TestHelper.java)                                                       | Contains utility methods for comparing objects, arrays and files                                                                                                                                                                                      |
 | [`AdditionalProperties`](./src/main/java/io/apimatic/core/types/AdditionalProperties.java)                                       | A generic class for managing additional properties in a model.                                                                                                                                                                                        |
 | [`ConversionHelper`](./src/main/java/io/apimatic/core/utilities/ConversionHelper.java)                                           | A Helper class for the coversion of type (provided as function) for all structures (array, map, array of map, n-dimensional arrays etc) supported in the SDK.                                                                                         |
+| [`HmacSignatureVerifier`](./src/main/java/io/apimatic/core/security/HmacSignatureVerifier.java)                                  | HMAC-based signature verifier for HTTP requests.                                                                                         |
+| [`DigestCodecFactory`](./src/main/java/io/apimatic/core/security/DigestCodecFactory.java)                                        | Factory class for creating digest codecs based on encoding type (Hex, Base64, Base64Url).                                                                                                                                                             |
 
 ## Interfaces
 
@@ -85,6 +87,7 @@ Core lib's Maven group ID is `io.apimatic`, and its artifact ID is `core`.
 | [`RequestSupplier`](./src/main/java/io/apimatic/core/request/async/RequestSupplier.java)           | A Request Supplier that supplies the request                                     |
 | [`TypeCombinator`](./src/main/java/io/apimatic/core/annotations/TypeCombinator.java)               | This is a container of annotations for oneOf/anyOf cases                         |
 | [`PaginationStrategy`](./src/main/java/io/apimatic/core/types/pagination/PaginationStrategy.java)  | Provides the functionality to apply pagination parameters and return new request |
+| [`DigestCodec`](./src/main/java/io/apimatic/core/security/DigestCodec.java)                        | Interface for encoding and decoding digest values                                |
 
 ## Links
 

src/main/java/io/apimatic/core/security/DigestCodec.java

@@ -0,0 +1,22 @@
+package io.apimatic.core.security;
+
+/**
+ * Interface for encoding and decoding digest values.
+ */
+public interface DigestCodec {
+    /**
+     * Encodes a byte array digest into a string representation.
+     *
+     * @param bytes The byte array to encode.
+     * @return The encoded string representation.
+     */
+    String encode(byte[] bytes);
+
+    /**
+     * Decodes a string representation back into a byte array.
+     *
+     * @param encoded The encoded string to decode.
+     * @return The decoded byte array.
+     */
+    byte[] decode(String encoded);
+}

src/main/java/io/apimatic/core/security/DigestCodecFactory.java

@@ -0,0 +1,99 @@
+package io.apimatic.core.security;
+
+import java.util.Base64;
+
+/**
+ * Factory class for creating digest codecs based on encoding type.
+ */
+public final class DigestCodecFactory {
+
+    private DigestCodecFactory() { } // Prevent instantiation
+
+    /**
+     * Creates a Hex codec.
+     * @return a DigestCodec for Hex encoding/decoding
+     */
+    public static DigestCodec hex() {
+        return new HexDigestCodec();
+    }
+
+    /**
+     * Creates a Base64 codec.
+     * @return a DigestCodec for Base64 encoding/decoding
+     */
+    public static DigestCodec base64() {
+        return new Base64DigestCodec();
+    }
+
+    /**
+     * Creates a Base64Url codec.
+     * @return a DigestCodec for Base64Url encoding/decoding
+     */
+    public static DigestCodec base64Url() {
+        return new Base64UrlDigestCodec();
+    }
+
+    private static final int HEX_RADIX = 16;
+    private static final int HEX_BYTE_MASK = 0xff;
+    private static final int HEX_BYTE_LENGTH = 2;
+    private static final int HEX_SHIFT = 4;
+
+    /**
+     * Codec for Hex encoding/decoding.
+     */
+    private static class HexDigestCodec implements DigestCodec {
+        @Override
+        public String encode(byte[] bytes) {
+            StringBuilder sb = new StringBuilder();
+            for (byte b : bytes) {
+                sb.append(String.format("%02x", b & HEX_BYTE_MASK));
+            }
+            return sb.toString();
+        }
+
+        @Override
+        public byte[] decode(String encoded) {
+            int len = encoded.length();
+            if (len % HEX_BYTE_LENGTH != 0) {
+                throw new IllegalArgumentException("Invalid hex string length.");
+            }
+            byte[] result = new byte[len / HEX_BYTE_LENGTH];
+            for (int i = 0; i < len; i += HEX_BYTE_LENGTH) {
+                result[i / HEX_BYTE_LENGTH] = (byte) (
+                        (Character.digit(encoded.charAt(i), HEX_RADIX) << HEX_SHIFT)
+                        + Character.digit(encoded.charAt(i + 1), HEX_RADIX));
+            }
+            return result;
+        }
+    }
+
+    /**
+     * Codec for Base64 encoding/decoding.
+     */
+    private static class Base64DigestCodec implements DigestCodec {
+        @Override
+        public String encode(byte[] bytes) {
+            return Base64.getEncoder().encodeToString(bytes);
+        }
+
+        @Override
+        public byte[] decode(String encoded) {
+            return Base64.getDecoder().decode(encoded);
+        }
+    }
+
+    /**
+     * Codec for Base64Url encoding/decoding.
+     */
+    private static class Base64UrlDigestCodec implements DigestCodec {
+        @Override
+        public String encode(byte[] bytes) {
+            return Base64.getUrlEncoder().withoutPadding().encodeToString(bytes);
+        }
+
+        @Override
+        public byte[] decode(String encoded) {
+            return Base64.getUrlDecoder().decode(encoded);
+        }
+    }
+}

src/main/java/io/apimatic/core/security/HmacSignatureVerifier.java

@@ -0,0 +1,217 @@
+package io.apimatic.core.security;
+
+import io.apimatic.coreinterfaces.http.request.Request;
+import io.apimatic.coreinterfaces.security.SignatureVerifier;
+import io.apimatic.coreinterfaces.security.VerificationResult;
+
+import javax.crypto.Mac;
+import javax.crypto.spec.SecretKeySpec;
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.util.Map;
+import java.util.concurrent.CompletableFuture;
+import java.util.function.Function;
+
+/**
+ * HMAC-based signature verifier for HTTP requests.
+ * <p>
+ * Supports signature templates such as:
+ * <ul>
+ *   <li>{@code Sha256={digest}}</li>
+ *   <li>{@code Sha256={digest}=abc}</li>
+ *   <li>{@code signature="{digest}"; ts=1690000000}</li>
+ * </ul>
+ * The template is matched inside the header value (noise tolerated before/after).
+ */
+public class HmacSignatureVerifier implements SignatureVerifier {
+    private static final String SIGNATURE_VALUE_PLACEHOLDER = "{digest}";
+
+    /** Name of the header carrying the provided signature (lookup is case-insensitive). */
+    private final String signatureHeaderName;
+
+    /** HMAC algorithm used for signature generation (default: HmacSHA256). */
+    private final String algorithm;
+
+    /** Initialized key spec; used to create a new Mac per verification call. */
+    private final SecretKeySpec keySpec;
+
+    /** Template containing "{digest}". */
+    private final String signatureValueTemplate;
+
+    /** Resolves the bytes to sign from the request. */
+    private final Function<Request, byte[]> requestBytesResolver;
+
+    /** Codec used to decode (and possibly encode) digest text ↔ bytes (e.g., hex/base64). */
+    private final DigestCodec digestCodec;
+
+    /**
+     * Initializes a new instance of the HmacSignatureVerifier class.
+     *
+     * @param secretKey Secret key for HMAC computation.
+     * @param signatureHeaderName Name of the header containing the signature.
+     * @param digestCodec Encoding type for the signature.
+     * @param requestBytesResolver Optional custom resolver for extracting data to sign.
+     * @param algorithm Algorithm (default HmacSHA256).
+     * @param signatureValueTemplate Template for signature format.
+     */
+    public HmacSignatureVerifier(
+            final String secretKey,
+            final String signatureHeaderName,
+            final DigestCodec digestCodec,
+            final Function<Request, byte[]> requestBytesResolver,
+            final String algorithm,
+            final String signatureValueTemplate
+    ) {
+
+        if (secretKey == null || secretKey.trim().isEmpty()) {
+            throw new IllegalArgumentException("Secret key cannot be null or Empty.");
+        }
+        if (signatureHeaderName == null || signatureHeaderName.trim().isEmpty()) {
+            throw new IllegalArgumentException("Signature header cannot be null or Empty.");
+        }
+        if (signatureValueTemplate == null || signatureValueTemplate.trim().isEmpty()) {
+            throw new IllegalArgumentException("Signature value template cannot be null or Empty.");
+        }
+        if (requestBytesResolver == null) {
+            throw new IllegalArgumentException(
+                    "Request signature template resolver function cannot be null.");
+        }
+        if (digestCodec == null) {
+            throw new IllegalArgumentException("Digest encoding cannot be null.");
+        }
+        if (algorithm == null || algorithm.trim().isEmpty()) {
+            throw new IllegalArgumentException("Algorithm cannot be null or Empty.");
+        }
+
+        this.signatureHeaderName = signatureHeaderName;
+        this.algorithm = algorithm;
+        this.keySpec = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), algorithm);
+        this.signatureValueTemplate = signatureValueTemplate;
+        this.requestBytesResolver = requestBytesResolver;
+        this.digestCodec = digestCodec;
+    }
+
+    /**
+     * Verifies the HMAC signature of the specified HTTP request.
+     *
+     * @param request The HTTP request to verify.
+     * @return A CompletableFuture containing the verification result.
+     */
+    @Override
+    public CompletableFuture<VerificationResult> verifyAsync(final Request request) {
+        return CompletableFuture.supplyAsync(() -> {
+            try {
+                String headerValue = request.getHeaders().asSimpleMap().entrySet().stream()
+                        .filter(e -> e.getKey() != null
+                                && e.getKey().equalsIgnoreCase(signatureHeaderName))
+                        .map(Map.Entry::getValue)
+                        .findFirst()
+                        .orElse(null);
+
+                if (headerValue == null) {
+                    return VerificationResult.failure(
+                            "Signature header '" + signatureHeaderName + "' is missing.");
+                }
+
+                byte[] provided = extractSignature(headerValue);
+                if (provided == null || provided.length == 0) {
+                    return VerificationResult.failure(
+                            "Malformed signature header '" + signatureHeaderName + "'.");
+                }
+
+                byte[] message = requestBytesResolver.apply(request);
+                // HMAC per call (thread-safe)
+                Mac mac = Mac.getInstance(algorithm);
+                mac.init(keySpec);
+                byte[] computed = mac.doFinal(message);
+
+                return MessageDigest.isEqual(provided, computed)
+                        ? VerificationResult.success()
+                        : VerificationResult.failure("Signature verification failed.");
+            } catch (Exception ex) {
+                return VerificationResult.failure("Exception: " + ex.getMessage());
+            }
+        });
+    }
+
+    /**
+     * Extracts the digest value from the signature header according to the template
+     * and decodes the signature from the header value.
+     *
+     * @param headerValue The value of the signature header.
+     * @return The decoded signature as a byte array, or null if extraction fails.
+     */
+    private byte[] extractSignature(final String headerValue) {
+        try {
+            int index = signatureValueTemplate.indexOf(SIGNATURE_VALUE_PLACEHOLDER);
+            if (index < 0) {
+                return new byte[0];
+            }
+
+            String prefix = signatureValueTemplate.substring(0, index);
+            String suffix = signatureValueTemplate.substring(
+                    index + SIGNATURE_VALUE_PLACEHOLDER.length());
+
+            // find prefix anywhere (case-insensitive)
+            int prefixAt = indexOfIgnoreCase(headerValue, prefix, 0);
+            if (prefixAt < 0) {
+                return new byte[0];
+            }
+
+            int digestStart = prefixAt + prefix.length();
+
+            // find suffix after the digest start (case-insensitive)
+            final int digestEnd;
+            if (suffix.isEmpty()) {
+                digestEnd = headerValue.length();
+            } else {
+                digestEnd = indexOfIgnoreCase(headerValue, suffix, digestStart);
+                if (digestEnd < 0) {
+                    return new byte[0];
+                }
+            }
+
+            if (digestEnd < digestStart) {
+                return new byte[0];
+            }
+
+            String digest = headerValue.substring(digestStart, digestEnd).trim();
+            // strip optional quotes
+            if (digest.length() >= 2 && digest.charAt(0) == '"'
+                    && digest.charAt(digest.length() - 1) == '"') {
+                digest = digest.substring(1, digest.length() - 1);
+            }
+
+            byte[] decoded = digestCodec.decode(digest);
+            return (decoded == null || decoded.length == 0) ? null : decoded;
+        } catch (Exception e) {
+            return new byte[0];
+        }
+    }
+
+    /**
+     * Finds the index of the first case-insensitive {@code needle} in {@code haystack}
+     * starting from {@code fromIndex}, or -1 if not found.
+     *
+     * @param haystack The string to search in.
+     * @param needle The substring to search for.
+     * @param fromIndex The index to start searching from.
+     * @return The index of the first occurrence, or -1 if not found.
+     */
+    private static int indexOfIgnoreCase(
+            final String haystack,
+            final String needle,
+            final int fromIndex
+    ) {
+        if (needle.isEmpty()) {
+            return fromIndex;
+        }
+        int max = haystack.length() - needle.length();
+        for (int i = Math.max(0, fromIndex); i <= max; i++) {
+            if (haystack.regionMatches(true, i, needle, 0, needle.length())) {
+                return i;
+            }
+        }
+        return -1;
+    }
+}