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 (GetStream\\StreamChat\\Client)

Static primitives:

• gunzipPayload(string): string — gzip-magic-byte detection, no-op when not compressed
• decodeSqsPayload(string): string — base64 decode then gunzip-if-magic
• decodeSnsPayload(notificationBody): string — 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(string, string, string): 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(string): array — JSON → associative array

Instance composites (return array):

• verifyAndParseWebhook(string \$body, string \$signature): array
• verifyAndParseSqs(string \$body, string \$signature): array
• verifyAndParseSns(string \$body, string \$signature): array

Typed Event objects will land in PHP in a follow-up release. Until then the helpers return the parsed JSON as an associative array.

Backwards compatibility

\$client->verifyWebhook(\$body, \$signature) is preserved and now delegates to Client::verifySignature. The experimental decompressWebhookBody and verifyAndDecodeWebhook surfaces are removed (they were never released).

Tests

tests/unit/WebhookCompressionTest.php covers plain / gzip / base64 / base64+gzip payloads, signature mismatches, malformed bytes, and JSON parsing into an associative array. 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

• PHPUnit (php 8.2 in Docker): 25 passed / 35 assertions
• php-cs-fixer fix — clean

[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 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::getPrevious() cause-chain.

Class name family: InvalidWebhookException — "Invalid" covers all failure modes accurately, consistent with stdlib naming patterns (InvalidArgumentException, 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 GetStream\StreamChat\InvalidWebhookException extending existing StreamException, replacing any per-mode exception classes 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. Legacy Client::verifyWebhook (returning bool) stays unchanged — back-compat preserved. The vestigial @throws StreamException PHPDoc on the legacy method should be removed since its body cannot throw.
5. Update PHPUnit 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.