refactor(webhooks): switch to verify_and_parse_* API (CHA-3071)

Replaces the earlier verify_and_decode_webhook surface with the
cross-SDK contract documented at
https://getstream.io/chat/docs/node/webhooks_overview/.

Module-level helpers in stream_chat.webhook:

  Primitives:
    ungzip_payload       - gzip magic-byte detection + inflate
    decode_sqs_payload   - base64 then ungzip-if-magic
    decode_sns_payload   - alias for decode_sqs_payload
    verify_signature     - constant-time HMAC-SHA256 comparison
    parse_event          - JSON -> dict (typed event lands later)

  Composite (return parsed event dict):
    verify_and_parse_webhook
    verify_and_parse_sqs
    verify_and_parse_sns

The composite functions auto-detect compression from body bytes, so
the same handler stays correct whether or not Stream is currently
compressing payloads, and behind middleware that auto-decompresses.

Client instance methods (StreamChat / StreamChatAsync) mirror the
three composite helpers with api_secret pulled from the client.

The legacy verify_webhook(body, x_signature) -> bool boolean helper
is unchanged for backward compatibility.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: nijeesh-stream

stream_chat/base/client.py

@@ -133,84 +133,66 @@ def verify_webhook(
         ).hexdigest()
         return signature == x_signature
 
-    def decompress_webhook_body(
+    def verify_and_parse_webhook(
         self,
         body: Union[bytes, str],
-        content_encoding: Optional[str] = None,
-        payload_encoding: Optional[str] = None,
-    ) -> bytes:
-        """Decode a (possibly compressed and/or wrapped) webhook payload.
-
-        Stream Chat can compress outbound webhook payloads with gzip and, for
-        SQS / SNS firehose delivery, also wrap the compressed bytes in base64
-        so they remain valid UTF-8 over the queue. This helper applies the
-        encodings in order:
-
-        1. ``payload_encoding`` (``"base64"`` / ``"b64"``) is unwrapped first.
-        2. ``content_encoding`` (``"gzip"``) is decompressed next.
-        3. The raw JSON bytes are returned. The caller can ``.decode("utf-8")``
-           or pass the value straight to :func:`json.loads`, which accepts
-           bytes.
-
-        ``None`` or an empty string for either encoding is a no-op, so the
-        regular HTTP webhook path stays bytewise identical to today.
-
-        This method does **not** check the ``X-Signature`` header. Use
-        :meth:`verify_and_decode_webhook` for the combined decode + verify
-        flow.
-
-        :param body: raw bytes (or str) received from Stream
-        :param content_encoding: value of the ``Content-Encoding`` header
-            (only ``"gzip"`` is supported)
-        :param payload_encoding: wrapper around the compressed bytes
-            (``"base64"`` / ``"b64"``); used by the SQS / SNS firehose
-        :returns: the uncompressed JSON body as bytes
-        """
-        from stream_chat.webhook import decompress_webhook_body
-
-        return decompress_webhook_body(
-            body,
-            content_encoding=content_encoding,
-            payload_encoding=payload_encoding,
-        )
+        signature: Union[str, bytes],
+    ) -> Dict[str, Any]:
+        """Verify and parse an HTTP webhook event.
+
+        Decompresses ``body`` when gzipped (detected from the body bytes),
+        verifies the ``X-Signature`` header against the app's API secret,
+        and returns the parsed event. The Python SDK currently returns a
+        ``dict``; typed event classes are planned for a future release.
 
-    def verify_and_decode_webhook(
+        :param body: raw HTTP request body bytes Stream signed
+        :param signature: ``X-Signature`` header value
+        :raises stream_chat.base.exceptions.WebhookSignatureError: on
+            signature mismatch or any decode error
+        """
+        from stream_chat.webhook import verify_and_parse_webhook
+
+        return verify_and_parse_webhook(body, signature, self.api_secret)
+
+    def verify_and_parse_sqs(
         self,
-        body: Union[bytes, str],
-        x_signature: Union[str, bytes],
-        content_encoding: Optional[str] = None,
-        payload_encoding: Optional[str] = None,
-    ) -> bytes:
-        """Decode a webhook payload and verify its HMAC-SHA256 signature.
-
-        The signature is always computed over the **uncompressed** JSON
-        payload, so this method first decodes the body via
-        :meth:`decompress_webhook_body` and then compares the digest with
-        ``x_signature`` using :func:`hmac.compare_digest`.
-
-        Works for plain HTTP webhooks (pass the ``Content-Encoding`` header
-        value) and for SQS / SNS firehose envelopes (additionally pass
-        ``payload_encoding="base64"``).
-
-        :param body: raw bytes (or str) received from Stream
-        :param x_signature: the ``X-Signature`` header value sent by Stream
-        :param content_encoding: value of the ``Content-Encoding`` header
-            (only ``"gzip"`` is supported)
-        :param payload_encoding: wrapper around the compressed bytes
-            (``"base64"`` / ``"b64"``); used by the SQS / SNS firehose
-        :returns: the verified, uncompressed JSON body as bytes
+        message_body: Union[bytes, str],
+        signature: Union[str, bytes],
+    ) -> Dict[str, Any]:
+        """Verify and parse an SQS firehose webhook event.
+
+        Reverses the base64 (+ optional gzip) wrapping on the SQS
+        ``Body``, verifies the ``X-Signature`` message attribute against
+        the app's API secret, and returns the parsed event.
+
+        :param message_body: SQS message ``Body`` (string)
+        :param signature: ``X-Signature`` message attribute value
         :raises stream_chat.base.exceptions.WebhookSignatureError: on
             signature mismatch or any decode error
         """
-        from stream_chat.webhook import verify_and_decode_webhook
+        from stream_chat.webhook import verify_and_parse_sqs
 
-        return verify_and_decode_webhook(
-            body,
-            x_signature,
-            api_secret=self.api_secret,
-            content_encoding=content_encoding,
-            payload_encoding=payload_encoding,
-        )
+        return verify_and_parse_sqs(message_body, signature, self.api_secret)
+
+    def verify_and_parse_sns(
+        self,
+        message: Union[bytes, str],
+        signature: Union[str, bytes],
+    ) -> Dict[str, Any]:
+        """Verify and parse an SNS firehose webhook event.
+
+        Reverses the base64 (+ optional gzip) wrapping on the SNS
+        ``Message``, verifies the ``X-Signature`` message attribute
+        against the app's API secret, and returns the parsed event.
+
+        :param message: SNS notification ``Message`` field (string)
+        :param signature: ``X-Signature`` message attribute value
+        :raises stream_chat.base.exceptions.WebhookSignatureError: on
+            signature mismatch or any decode error
+        """
+        from stream_chat.webhook import verify_and_parse_sns
+
+        return verify_and_parse_sns(message, signature, self.api_secret)
 
     @abc.abstractmethod
     def update_app_settings(