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 (StreamChat.Clients.WebhookHelpers)

WebhookHelpers is now public so apps can compose the primitives directly:

• 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 EventResponse via Newtonsoft.Json

Composites on IAppClient (return a typed EventResponse):

• VerifyAndParseWebhook(byte[], string)
• VerifyAndParseSqs(string, string)
• VerifyAndParseSns(string, string)

Backwards compatibility

AppClient.VerifyWebhook is preserved and now uses the same constant-time HMAC-SHA256 path. The legacy VerifyAndDecodeWebhook surface is removed (it was experimental and not yet released).

Unified error handling

Per cross-SDK coordination (mogita's review across the 6 sibling SDK PRs), every webhook failure path now terminates at a single exception class — StreamInvalidWebhookException (extends StreamBaseException) so customers only need one catch arm. The message text identifies which failure mode fired so callers that want to differentiate (security logging, retry policy) can filter on substring:

Failure mode	Message
Signature mismatch	signature mismatch
Base64 decode	invalid base64 encoding
Gzip decompression	gzip decompression failed
JSON parse	invalid JSON payload

public const string failure-mode constants on the class (StreamInvalidWebhookException.SignatureMismatch etc.) are available for exact-match filtering. The legacy AppClient.VerifyWebhook (bool return) is untouched.

Tests

tests/WebhookCompressionTests.cs covers plain / gzip / base64 / base64+gzip payloads, signature mismatches, malformed bytes, and JSON parsing into EventResponse. 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

• dotnet build — clean
• dotnet test --filter ~WebhookCompressionTests — 22 passed

[mogita]

Cross-SDK review pass for CHA-3071. Three 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 Exception.InnerException chain.

Class name family: StreamInvalidWebhookException — "Invalid" covers all failure modes accurately, consistent with BCL naming patterns (InvalidOperationException, InvalidCastException, 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. Rename StreamWebhookSignatureException → StreamInvalidWebhookException, extending the existing StreamBaseException in src/Exceptions/
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 (this resolves the inline comment about JSON parse failures being misleadingly wrapped in a "Signature" exception type)
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. Legacy AppClient.VerifyWebhook (returning bool) stays unchanged in return type — back-compat preserved. Separate inline comment about its naive sig == xSignature comparison still applies.
5. Update xUnit 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.

[nijeesh-stream]

Shipped in 6bf2dcb along with the SNS envelope fix.

• StreamWebhookSignatureException → StreamInvalidWebhookException (extends StreamBaseException, file renamed at src/Exceptions/StreamInvalidWebhookException.cs)
• public const string SignatureMismatch / InvalidBase64 / GzipFailed / InvalidJson on the class for exact-match filtering; inner exceptions (InvalidDataException, IOException, FormatException, JsonException) chained through the (string, Exception) constructor
• GunzipPayload now catches both InvalidDataException and IOException to cover the full range of malformed-gzip cases. VerifySignature keeps its bool return; composite VerifyAndParse* helpers throw on mismatch via VerifyAndParseInternal. Legacy AppClient.VerifyWebhook (bool return) is untouched
• tests/WebhookCompressionTests.cs: 36 passed (was 33); WithMessage calls converted to substring wildcards (*signature mismatch*, *invalid base64 encoding*, etc.) and the three required failure-mode tests added. dotnet build clean (the 6 NETSDK1138 warnings on samples/* are pre-existing)
• Full-repo grep confirms zero StreamWebhookSignatureException references remain

Docs side, docs-content#1276 now carries the per-SDK error-class table on the Webhooks overview page.