refactor(webhooks): unify webhook errors under InvalidWebhookException (CHA-3071)

Per cross-SDK coordination (mogita's review on all 6 sibling SDK PRs),
every webhook failure path now terminates at a single exception class.
Customers only need one catch arm and can filter by getMessage() text
for mode-specific behaviour.

Renames the previously-unreleased WebhookSignatureException to
InvalidWebhookException (still extends StreamException) and threads it
through every primitive:

  verifyAndParseWebhook -> 'signature mismatch'
  gunzipPayload         -> 'gzip decompression failed'
  decodeSqsPayload      -> 'invalid base64 encoding'
  parseEvent            -> 'invalid JSON payload'

verifySignature keeps its boolean return at the primitive layer; the
composite verifyAndParse* helpers throw on mismatch. The legacy
Client#verifyWebhook helper (bool return) is untouched.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: nijeesh-stream

build.gradle

@@ -39,6 +39,7 @@ dependencies {
 	runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.12.5'
 	runtimeOnly 'io.jsonwebtoken:jjwt-jackson:0.12.5'
 	testImplementation 'org.junit.jupiter:junit-jupiter-engine:5.8.2'
+	testImplementation 'org.assertj:assertj-core:3.27.3'
 	testImplementation 'org.apache.commons:commons-lang3:3.12.0'
 	compileOnly 'org.jetbrains:annotations:24.1.0'
 }

docs/webhooks/webhooks_overview/webhooks_overview.md

@@ -122,7 +122,7 @@ boolean valid = App.verifySignature(json, signature, apiSecret);
 Event event = App.parseEvent(json);
 ```
 
-Detection is done via the gzip magic bytes (`1f 8b`, per RFC 1952), so the same helper stays correct whether or not your HTTP server already decompressed the body for you. Any non-gzip body is passed through unchanged. Malformed gzip envelopes raise an `IllegalStateException`.
+Detection is done via the gzip magic bytes (`1f 8b`, per RFC 1952), so the same helper stays correct whether or not your HTTP server already decompressed the body for you. Any non-gzip body is passed through unchanged. Every webhook ingestion primitive (`gunzipPayload`, `decodeSqsPayload`, `decodeSnsPayload`, `parseEvent`, and the `verifyAndParse*` helpers) raises `InvalidWebhookException` on failure — one catch arm covers signature mismatches, malformed gzip envelopes, invalid base64, and invalid JSON; the failure-mode message constants on the exception class let callers branch when needed.
 
 #### SQS / SNS payloads
 

src/main/java/io/getstream/chat/java/exceptions/InvalidWebhookException.java

@@ -0,0 +1,26 @@
+package io.getstream.chat.java.exceptions;
+
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Raised by every webhook ingestion primitive when the request cannot be safely turned into a typed
+ * event. A single exception type lets handler code use one catch arm and, when needed, branch on
+ * the failure-mode message constants exposed here.
+ */
+public class InvalidWebhookException extends StreamException {
+  private static final long serialVersionUID = 1L;
+
+  public static final String SIGNATURE_MISMATCH = "signature mismatch";
+  public static final String INVALID_BASE64 = "invalid base64 encoding";
+  public static final String GZIP_FAILED = "gzip decompression failed";
+  public static final String INVALID_JSON = "invalid JSON payload";
+
+  public InvalidWebhookException(@NotNull String message) {
+    super(message, (Throwable) null);
+  }
+
+  public InvalidWebhookException(@NotNull String message, @Nullable Throwable cause) {
+    super(message, cause);
+  }
+}

src/main/java/io/getstream/chat/java/models/App.java

@@ -15,6 +15,7 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
 import com.fasterxml.jackson.databind.util.StdDateFormat;
+import io.getstream.chat.java.exceptions.InvalidWebhookException;
 import io.getstream.chat.java.models.App.AppCheckPushRequestData.AppCheckPushRequest;
 import io.getstream.chat.java.models.App.AppCheckSnsRequestData.AppCheckSnsRequest;
 import io.getstream.chat.java.models.App.AppCheckSqsRequestData.AppCheckSqsRequest;
@@ -1532,14 +1533,14 @@ public static boolean verifySignature(
    * <p>Magic-byte detection (rather than relying on a header) lets the same handler stay correct
    * when middleware auto-decompresses the request before your code sees it.
    */
-  public static byte[] gunzipPayload(@NotNull byte[] body) {
+  public static byte[] gunzipPayload(@NotNull byte[] body) throws InvalidWebhookException {
     if (body.length < 2 || body[0] != GZIP_MAGIC[0] || body[1] != GZIP_MAGIC[1]) {
       return body;
     }
     try (GZIPInputStream in = new GZIPInputStream(new ByteArrayInputStream(body))) {
       return readAll(in);
     } catch (IOException e) {
-      throw new IllegalStateException("failed to decompress gzip payload", e);
+      throw new InvalidWebhookException(InvalidWebhookException.GZIP_FAILED, e);
     }
   }
 
@@ -1551,12 +1552,12 @@ public static byte[] gunzipPayload(@NotNull byte[] body) {
    * @param body the SQS message {@code Body}
    * @return the raw JSON bytes Stream signed
    */
-  public static byte[] decodeSqsPayload(@NotNull String body) {
+  public static byte[] decodeSqsPayload(@NotNull String body) throws InvalidWebhookException {
     byte[] decoded;
     try {
       decoded = Base64.getDecoder().decode(body);
     } catch (IllegalArgumentException e) {
-      throw new IllegalStateException("failed to base64-decode payload", e);
+      throw new InvalidWebhookException(InvalidWebhookException.INVALID_BASE64, e);
     }
     return gunzipPayload(decoded);
   }
@@ -1568,7 +1569,8 @@ public static byte[] decodeSqsPayload(@NotNull String body) {
    * JSON envelope it is treated as the already-extracted {@code Message} string, so call sites that
    * pre-unwrap continue to work.
    */
-  public static byte[] decodeSnsPayload(@NotNull String notificationBody) {
+  public static byte[] decodeSnsPayload(@NotNull String notificationBody)
+      throws InvalidWebhookException {
     String inner = extractSnsMessage(notificationBody);
     return decodeSqsPayload(inner != null ? inner : notificationBody);
   }
@@ -1623,20 +1625,21 @@ private static ObjectMapper buildWebhookObjectMapper() {
    * unknown enum values are tolerated so the handler stays forward-compatible with new Stream
    * server releases.
    *
-   * @throws IllegalStateException when the bytes are not valid JSON
+   * @throws InvalidWebhookException when the bytes are not valid JSON
    */
-  public static @NotNull Event parseEvent(@NotNull byte[] payload) {
+  public static @NotNull Event parseEvent(@NotNull byte[] payload) throws InvalidWebhookException {
     try {
       return WEBHOOK_OBJECT_MAPPER.readValue(payload, Event.class);
     } catch (IOException e) {
-      throw new IllegalStateException("failed to parse webhook event", e);
+      throw new InvalidWebhookException(InvalidWebhookException.INVALID_JSON, e);
     }
   }
 
   private static @NotNull Event verifyAndParseInternal(
-      @NotNull byte[] payload, @NotNull String signature, @NotNull String secret) {
+      @NotNull byte[] payload, @NotNull String signature, @NotNull String secret)
+      throws InvalidWebhookException {
     if (!verifySignature(payload, signature, secret)) {
-      throw new SecurityException("invalid webhook signature");
+      throw new InvalidWebhookException(InvalidWebhookException.SIGNATURE_MISMATCH);
     }
     return parseEvent(payload);
   }
@@ -1650,17 +1653,18 @@ private static ObjectMapper buildWebhookObjectMapper() {
    * @param signature value of the {@code X-Signature} header
    * @param secret the app's API secret
    * @return the parsed event
-   * @throws SecurityException when the signature does not match
-   * @throws IllegalStateException when the gzip envelope is malformed or the payload is not JSON
+   * @throws InvalidWebhookException when the signature does not match, the gzip envelope is
+   *     malformed, or the payload is not JSON
    */
   public static @NotNull Event verifyAndParseWebhook(
-      @NotNull byte[] body, @NotNull String signature, @NotNull String secret) {
+      @NotNull byte[] body, @NotNull String signature, @NotNull String secret)
+      throws InvalidWebhookException {
     return verifyAndParseInternal(gunzipPayload(body), signature, secret);
   }
 
   /** Singleton-secret overload: uses the API secret of the configured {@link Client} singleton. */
   public static @NotNull Event verifyAndParseWebhook(
-      @NotNull byte[] body, @NotNull String signature) {
+      @NotNull byte[] body, @NotNull String signature) throws InvalidWebhookException {
     return verifyAndParseWebhook(body, signature, Client.getInstance().getApiSecret());
   }
 
@@ -1669,13 +1673,14 @@ private static ObjectMapper buildWebhookObjectMapper() {
    * from the {@code X-Signature} message attribute, and return the parsed {@link Event}.
    */
   public static @NotNull Event verifyAndParseSqs(
-      @NotNull String messageBody, @NotNull String signature, @NotNull String secret) {
+      @NotNull String messageBody, @NotNull String signature, @NotNull String secret)
+      throws InvalidWebhookException {
     return verifyAndParseInternal(decodeSqsPayload(messageBody), signature, secret);
   }
 
   /** Singleton-secret overload of {@link #verifyAndParseSqs(String, String, String)}. */
   public static @NotNull Event verifyAndParseSqs(
-      @NotNull String messageBody, @NotNull String signature) {
+      @NotNull String messageBody, @NotNull String signature) throws InvalidWebhookException {
     return verifyAndParseSqs(messageBody, signature, Client.getInstance().getApiSecret());
   }
 
@@ -1684,13 +1689,14 @@ private static ObjectMapper buildWebhookObjectMapper() {
    * signature} from the {@code X-Signature} message attribute, and return the parsed {@link Event}.
    */
   public static @NotNull Event verifyAndParseSns(
-      @NotNull String message, @NotNull String signature, @NotNull String secret) {
+      @NotNull String message, @NotNull String signature, @NotNull String secret)
+      throws InvalidWebhookException {
     return verifyAndParseInternal(decodeSnsPayload(message), signature, secret);
   }
 
   /** Singleton-secret overload of {@link #verifyAndParseSns(String, String, String)}. */
-  public static @NotNull Event verifyAndParseSns(
-      @NotNull String message, @NotNull String signature) {
+  public static @NotNull Event verifyAndParseSns(@NotNull String message, @NotNull String signature)
+      throws InvalidWebhookException {
     return verifyAndParseSns(message, signature, Client.getInstance().getApiSecret());
   }
 

src/main/java/io/getstream/chat/java/services/framework/Client.java

@@ -1,5 +1,6 @@
 package io.getstream.chat.java.services.framework;
 
+import io.getstream.chat.java.exceptions.InvalidWebhookException;
 import io.getstream.chat.java.models.App;
 import io.getstream.chat.java.models.Event;
 import java.time.Duration;
@@ -31,7 +32,8 @@ public interface Client {
    * @param signature value of the {@code X-Signature} header
    * @return parsed {@link Event}
    */
-  default @NotNull Event verifyAndParseWebhook(@NotNull byte[] body, @NotNull String signature) {
+  default @NotNull Event verifyAndParseWebhook(@NotNull byte[] body, @NotNull String signature)
+      throws InvalidWebhookException {
     return App.verifyAndParseWebhook(body, signature, getApiSecret());
   }
 
@@ -44,7 +46,8 @@ public interface Client {
    * @param signature value of the {@code X-Signature} message attribute
    * @return parsed {@link Event}
    */
-  default @NotNull Event verifyAndParseSqs(@NotNull String messageBody, @NotNull String signature) {
+  default @NotNull Event verifyAndParseSqs(@NotNull String messageBody, @NotNull String signature)
+      throws InvalidWebhookException {
     return App.verifyAndParseSqs(messageBody, signature, getApiSecret());
   }
 
@@ -57,7 +60,8 @@ public interface Client {
    * @param signature value of the {@code X-Signature} message attribute
    * @return parsed {@link Event}
    */
-  default @NotNull Event verifyAndParseSns(@NotNull String message, @NotNull String signature) {
+  default @NotNull Event verifyAndParseSns(@NotNull String message, @NotNull String signature)
+      throws InvalidWebhookException {
     return App.verifyAndParseSns(message, signature, getApiSecret());
   }