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 (src/signing.ts)

Primitives:

• gunzipPayload(body) — gzip-magic-byte detection, no-op when not compressed
• decodeSqsPayload(body) — strict 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(body, signature, secret) — 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) — JSON → typed Event<…>

Composites (return a typed Event<…>):

• verifyAndParseWebhook(body, signature, secret)
• verifyAndParseSqs(body, signature, secret)
• verifyAndParseSns(body, signature, secret)

StreamChat#verifyAndParseWebhook / verifyAndParseSqs / verifyAndParseSns use the configured client secret automatically.

Backwards compatibility

• StreamChat#verifyWebhook is preserved and now delegates to verifySignature (same constant-time HMAC-SHA256).
• CheckSignature is deprecated and aliases verifySignature.
• A new WebhookSignatureError is thrown by composites on signature mismatch.

Tests

test/unit/webhook-compression.test.ts 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

• yarn vitest run test/unit/webhook-compression.test.ts — 35 passed
• yarn lint — clean on touched files
• yarn prettier:check — clean

[github-actions]

Size Change: +3.99 kB (+1.05%)

Total Size: 385 kB

📦 View Changed

Filename	Size	Change
dist/cjs/index.browser.js	128 kB	+1.32 kB (+1.04%)
dist/cjs/index.node.js	129 kB	+1.37 kB (+1.07%)
dist/esm/index.mjs	127 kB	+1.3 kB (+1.03%)

_{compressed-size-action}

[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 exception class rather than the split (signature vs parse) 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 cause-chain.

Class name family: InvalidWebhookError — "Invalid" covers all failure modes accurately (it's the standard stdlib term across all target languages: InvalidArgumentException, InvalidOperationException, ValueError, etc., as opposed to "Parse" which would undersell the signature-failure case).

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 WebhookSignatureError → InvalidWebhookError
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. Legacy verifyWebhook (returning bool) stays unchanged — back-compat preserved
5. Update unit 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.