feat(webhooks): verify_and_parse_* 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 verify_and_parse_* API that mirrors the cross-SDK contract published in Webhooks Overview.

New public API (stream_chat/webhook.py)

Module-level primitives:

• gunzip_payload(body) -> bytes — gzip-magic-byte detection, no-op when not compressed
• decode_sqs_payload(body) -> bytes — base64-decode then gunzip-if-magic
• decode_sns_payload(notification_body) -> bytes — 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
• verify_signature(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)
• parse_event(payload) -> dict — JSON → dict

Module-level composites (return dict):

• verify_and_parse_webhook(body, signature, secret) -> dict
• verify_and_parse_sqs(body, signature, secret) -> dict
• verify_and_parse_sns(body, signature, secret) -> dict

StreamChat/StreamChatAsync instances expose verify_and_parse_webhook / verify_and_parse_sqs / verify_and_parse_sns that use the configured api_secret automatically.

Typed Event objects will land in Python in a follow-up release. Until then the helpers return the parsed JSON as a dict.

Backwards compatibility

StreamChat#verify_webhook is preserved for plain (uncompressed) bodies. The experimental decompress_webhook_body and verify_and_decode_webhook 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 — InvalidWebhookError so customers only need one except 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

Module-level constants (INVALID_WEBHOOK_SIGNATURE_MISMATCH / INVALID_WEBHOOK_INVALID_BASE64 / INVALID_WEBHOOK_GZIP_FAILED / INVALID_WEBHOOK_INVALID_JSON) are exported for callers that prefer exact-match filtering. The legacy StreamChat#verify_webhook (bool return) is untouched.

Tests

stream_chat/tests/test_webhook_compression.py covers plain / gzip / base64 / base64+gzip payloads, signature mismatches, malformed bytes, JSON parsing into dict, and the StreamChat / StreamChatAsync client-bound paths. 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

• pytest stream_chat/tests/test_webhook_compression.py — 59 passed (was 57)
• black / isort — clean