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

Primitives (in webhook.go, intended to be composable):

• GunzipPayload(body) ([]byte, error) — gzip-magic-byte detection, no-op when not compressed
• DecodeSqsPayload(body) ([]byte, error) — base64 decode then gunzip-if-magic
• DecodeSnsPayload(notificationBody) ([]byte, error) — 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(body, signature, secret) bool — 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(payload) (*Event, error) — JSON → typed *Event

Composites (return a typed *Event):

• VerifyAndParseWebhook(body, signature, secret) (*Event, error)
• VerifyAndParseSqs(body, signature, secret) (*Event, error)
• VerifyAndParseSns(body, signature, secret) (*Event, error)

Client-bound versions on *Client use the configured app secret automatically.

Backwards compatibility

Client.VerifyWebhook is preserved and delegates to VerifySignature. Existing callers continue to work unchanged for plain (uncompressed) bodies.

Tests

webhook_test.go covers plain / gzip / base64 / base64+gzip payloads, signature mismatches, malformed bytes, JSON parsing into *Event, and a backwards-compat path for Client.VerifyWebhook. 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

• go vet ./... clean
• go test -c . (test binary compiles clean)
• Full go test ./... runs in CI (package init() requires STREAM_KEY / STREAM_SECRET)

[mogita]

Cross-SDK review pass for CHA-3071. Two 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 error type rather than the split (signature vs parse sentinels) 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 error-handling branch 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 error message text or errors.Unwrap cause-chain.

Sentinel name: ErrInvalidWebhook (+ struct type InvalidWebhookError) — "Invalid" covers all failure modes accurately and is consistent with Go stdlib naming (errors.ErrUnsupported, etc., where the prefix Err names the category).

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. Consolidate the existing sentinels (ErrInvalidSignature, ErrMalformedWebhook, etc.) into a single ErrInvalidWebhook sentinel, with concrete struct InvalidWebhookError carrying details
2. Wrap all failure paths to return that single sentinel — signature mismatch, gzip failure, base64 failure, SNS envelope failure, JSON parse failure, missing type/schema failure — using fmt.Errorf("%w: <mode>: %v", ErrInvalidWebhook, cause) so errors.Is(err, ErrInvalidWebhook) matches and errors.Unwrap reaches the cause
3. The wrapped message identifies which failure mode fired ("signature mismatch", "invalid base64", "missing type field") so customers can filter on substring
4. Legacy Client.VerifyWebhook (returning bool) stays unchanged — back-compat preserved. Note: there's an existing review comment on AppClient.cs-equivalent in another SDK about the legacy method's bytes.Equal not being timing-safe; same applies to client.go:160, but that's separate from this exception-unification ask.
5. Update unit tests to assert via errors.Is(err, stream.ErrInvalidWebhook); for mode-specific tests, also assert on error message 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.