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).

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 — InvalidWebhookException (extends StreamException) 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 failure-mode messages on the class (InvalidWebhookException::SIGNATURE_MISMATCH etc.) are available for exact-match filtering. The legacy Client#verifyWebhook (bool return) is untouched.

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.

[nijeesh-stream]

Shipped in 619e75c along with the SNS envelope fix.

• New class \GetStream\StreamChat\InvalidWebhookException extending StreamException (the failure paths previously threw plain StreamException with ad-hoc messages — no WebhookSignatureException ever existed on this branch, so this is a clean introduction, not a rename)
• public const SIGNATURE_MISMATCH / INVALID_BASE64 / GZIP_FAILED / INVALID_JSON on the class for exact-match filtering; JsonException chained via $previous
• verifySignature keeps its primitive bool contract; composite verifyAndParse* helpers throw on mismatch
• Legacy Client#verifyWebhook (bool return) is untouched
• tests/unit/WebhookCompressionTest.php: 43 tests / 65 assertions (was 39) — every failure assertion migrated from StreamException + regex to InvalidWebhookException + exact expectExceptionMessage(InvalidWebhookException::*); added the three spec-named tests plus an inheritance invariant. Full unit suite green in Docker (php:8.3-cli + PHPUnit 9.6.22)

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