feat(webhooks): verifyAndParse* API for compressed payloads (CHA-3071)

[nijeesh-stream]

Summary

Adds first-class support for gzip-compressed webhook payloads (HTTP webhooks, SQS, SNS) and exposes a stable verifyAndParse* API that mirrors the cross-SDK contract published in Webhooks Overview.

New public API (io.getstream.chat.java.models.App)

Primitives:

• gunzipPayload(byte[]) — gzip-magic-byte detection, no-op when not compressed
• decodeSqsPayload(String) — base64 decode then gunzip-if-magic
• decodeSnsPayload(notificationBody) — JSON-parse the SNS HTTP notification envelope, extract the inner Message, then run the SQS pipeline. Falls through to a pre-extracted Message string when the input is not a JSON envelope
• verifySignature(byte[], String, String) — HMAC-SHA256 over the uncompressed body, with a constant-time comparison (matters for the HTTP webhook path where the X-Signature header is exposed publicly; SQS / SNS deliveries arrive over AWS-internal transports where timing-attack resistance is not strictly required)
• parseEvent(byte[]) — JSON → typed Event via Jackson

Composites (return a typed Event):

• verifyAndParseWebhook(byte[], String, String)
• verifyAndParseSqs(String, String, String)
• verifyAndParseSns(String, String, String)

Each composite has an overload that resolves the secret from the configured singleton client.

Backwards compatibility

verifyWebhook and verifyWebhookSignature are preserved and delegate to the new verifySignature helper. Existing callers continue to work for plain (uncompressed) bodies.

Tests

WebhookCompressionTest covers plain / gzip / base64 / base64+gzip payloads, signature mismatches, malformed bytes, and JSON parsing into Event. Linked Linear ticket: CHA-3071.

Golden test fixtures (Tommaso)

Added shared reference fixtures to the test suite so future SDKs can sanity-check decoders against the same payloads:

aGVsbG93b3JsZA==                          -> helloworld   (base64)
H4sIAGrYAWoAA8tIzcnJL88vykkBAK0g6/kKAAAA -> helloworld   (base64 + gzip)

Test plan

• ./gradlew test --tests io.getstream.chat.java.WebhookCompressionTest — all green (run via amazoncorretto:11 Docker image)
• ./gradlew build — passes

[mogita]

Cross-SDK review pass for CHA-3071. Four inline comments — see below.

[mogita]

Cross-SDK coordination: unifying webhook exception types

After the review pass across all 6 SDKs in this rollout and team discussion, we're consolidating the new webhook exception strategy to a single unified exception class rather than the split (signature vs parse exceptions) being introduced in this PR.

The Webhook Handling Spec on Notion (CHA-2961) has been revised to reflect this — §5.2 / §5.3 / §7 now specify a single class.

Why unified: From a customer's perspective, all failure modes — signature mismatch, gzip decompression failure, base64 decode failure, SNS envelope failure, JSON parse failure, missing schema field — terminate at the same catch block in customer code. A signature/parse split adds structural complexity without changing customer behavior. Customers who want to filter security logs for signature mismatches specifically can do so via exception message text or Throwable#getCause() chain.

Class name family: InvalidWebhookException — "Invalid" covers all failure modes accurately, consistent with JDK naming patterns (IllegalArgumentException, InvalidObjectException, etc.).

Per-SDK naming across the rollout:

SDK	Class name
JS	InvalidWebhookError (extends Error)
Python	InvalidWebhookError
Go	sentinel ErrInvalidWebhook + struct InvalidWebhookError
Java	InvalidWebhookException (extends existing StreamException)
PHP	InvalidWebhookException (extends existing StreamException)
Ruby	StreamChat::InvalidWebhookError (extends StandardError)
.NET	StreamInvalidWebhookException (extends StreamBaseException)

Asks for this PR:

1. Introduce io.getstream.chat.java.exceptions.InvalidWebhookException extending existing StreamException, replacing the IllegalStateException (or any per-mode exceptions) introduced in this PR
2. Wrap all failure paths into this single type — signature mismatch, gzip failure, base64 failure, SNS envelope failure, JSON parse failure, missing type/schema failure
3. Attach a human-readable message identifying which failure mode fired (e.g. "signature mismatch", "invalid base64", "missing type field") so customers can filter on message content
4. parseEvent return-type fix (already raised in inline comment on App.java:1599) — returning Optional<Event> or modeling UnknownEvent as a real subclass interacts with this exception change; both should be resolved together
5. Legacy verifyWebhookSignature (returning boolean) stays unchanged — back-compat preserved
6. Update JUnit tests to assert against the new exception name; for mode-specific tests, also assert on message-content substrings

This same comment is being posted on all 6 SDK PRs (JS / Go / Ruby / PHP / Java / .NET) for coordination. Happy to discuss naming or scope tradeoffs.