fix(webhooks): parseSqs/ParseSns decode-only; HTTP verify via verifyAndParseWebhook; docs + tests

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

Author: nijeesh-stream

docs/webhooks/webhooks_overview/webhooks_overview.md

@@ -143,46 +143,40 @@ The original `client.verify_webhook(request.body, request.headers["X-Signature"]
 
 For events delivered through SQS or SNS, call the matching helper. It base64-decodes the envelope, gzip-decompresses when the magic bytes are present, and returns the parsed event.
 
-Stream does **not** ship an `X-Signature` on SQS or SNS deliveries: those transports run on AWS-internal infrastructure that is already authenticated end-to-end. SQS queues are reached via IAM-authenticated polling, and SNS notifications carry an AWS signature on the notification envelope itself, so verifying that the message really came from your topic happens at the AWS layer. Layering an HMAC check on top is redundant, so `signature` and `secret` are optional for the SQS/SNS helpers. If you want the legacy verification pipeline you can still pass both — but you do not need to.
+Stream does **not** ship an `X-Signature` on SQS or SNS deliveries: those transports run on AWS-internal infrastructure that is already authenticated end-to-end. SQS queues are reached via IAM-authenticated polling, and SNS notifications carry an AWS signature on the notification envelope itself, so verifying that the message really came from your topic happens at the AWS layer. Layering an HMAC check on top is redundant, so the SQS/SNS helpers only decode and parse — they take a single argument and never verify a signature.
 
 For SQS, pass the message `Body` (already the payload):
 
 ```python
-event = client.verify_and_parse_sqs(sqs_message["Body"])
+event = client.parse_sqs(sqs_message["Body"])
 ```
 
 For SNS, pass the **raw notification body** (the full `{"Type":"Notification", ...}` JSON envelope Amazon delivers). The SDK extracts the inner `Message` field for you, so the call site mirrors what HTTP frameworks already hand you in `request.body`:
 
 ```python
 # Django SNS HTTP delivery
-event = client.verify_and_parse_sns(request.body)        # raw envelope (bytes/str)
+event = client.parse_sns(request.body)        # raw envelope (bytes/str)
 ```
 
 #### Stateless / module-level form
 
-If you do not want to construct a `StreamChat` client (for example in a lightweight Lambda that only handles webhooks), call the module-level helpers directly. The HTTP helper still requires the signature and secret; the SQS/SNS helpers take them as optional positional arguments:
+If you do not want to construct a `StreamChat` client (for example in a lightweight Lambda that only handles webhooks), call the module-level helpers directly. The HTTP helper still requires the signature and secret; the SQS/SNS helpers take a single argument:
 
 ```python
 from stream_chat import webhook
 
 event = webhook.verify_and_parse_webhook(body, signature, secret)
-event = webhook.verify_and_parse_sqs(message_body)
-event = webhook.verify_and_parse_sns(notification_body)
-
-# Opt-in HMAC verification for SQS / SNS (defence in depth)
-event = webhook.verify_and_parse_sqs(message_body, signature, secret)
-event = webhook.verify_and_parse_sns(notification_body, signature, secret)
+event = webhook.parse_sqs(message_body)
+event = webhook.parse_sns(notification_body)
 ```
 
-Passing only one of `signature` / `secret` to the SQS or SNS helper is a programmer error and raises `InvalidWebhookError("signature and secret must both be provided to verify the SQS/SNS payload")`.
-
 ##### Arguments
 
-| Argument            | `verify_and_parse_webhook` | `verify_and_parse_sqs` | `verify_and_parse_sns` |
-| ------------------- | -------------------------- | ---------------------- | ---------------------- |
+| Argument            | `verify_and_parse_webhook` | `parse_sqs`     | `parse_sns`          |
+| ------------------- | -------------------------- | --------------- | -------------------- |
 | body / message_body / notification_body | required | required | required |
-| signature           | required                   | optional               | optional               |
-| secret              | required                   | optional               | optional               |
+| signature           | required                   | —               | —                    |
+| secret              | required                   | —               | —                    |
 
 The module also exposes the primitives the composites are built from — `gunzip_payload`, `decode_sqs_payload`, `decode_sns_payload`, `verify_signature` (constant-time HMAC-SHA256), and `parse_event` — for callers that need to run the steps individually.
 

stream_chat/base/client.py

@@ -147,68 +147,26 @@ def verify_and_parse_webhook(
 
         :param body: raw HTTP request body bytes Stream signed
         :param signature: ``X-Signature`` header value
-        :raises stream_chat.webhook.InvalidWebhookError: on
+        :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,
-        message_body: Union[bytes, str],
-        signature: Optional[Union[str, bytes]] = None,
-    ) -> Dict[str, Any]:
-        """Parse an SQS firehose webhook event.
-
-        Reverses the base64 (+ optional gzip) wrapping on the SQS
-        ``Body`` and returns the parsed event. Stream does not attach
-        an ``X-Signature`` to SQS deliveries -- the transport is an
-        IAM-authenticated AWS queue, so HMAC verification on top is
-        redundant and signature verification is therefore optional.
-        When ``signature`` is supplied the app's API secret is used to
-        run the legacy verification pipeline.
-
-        :param message_body: SQS message ``Body`` (string)
-        :param signature: optional ``X-Signature`` message attribute
-            value; when supplied, signature verification runs
-        :raises stream_chat.webhook.InvalidWebhookError: on
-            signature mismatch or any decode error
-        """
-        from stream_chat.webhook import verify_and_parse_sqs
+    def parse_sqs(self, message_body: Union[bytes, str]) -> Dict[str, Any]:
+        """Parse an SQS firehose body (base64 + optional gzip). No HMAC."""
 
-        if signature is None:
-            return verify_and_parse_sqs(message_body)
-        return verify_and_parse_sqs(message_body, signature, self.api_secret)
+        from stream_chat.webhook import parse_sqs
 
-    def verify_and_parse_sns(
-        self,
-        notification_body: Union[bytes, str],
-        signature: Optional[Union[str, bytes]] = None,
-    ) -> Dict[str, Any]:
-        """Parse an SNS firehose webhook event.
-
-        Reverses the base64 (+ optional gzip) wrapping on the SNS
-        ``Message`` and returns the parsed event. Stream does not
-        attach an ``X-Signature`` to SNS deliveries -- AWS already
-        signs the SNS notification envelope, so HMAC verification on
-        top is redundant and signature verification is therefore
-        optional. When ``signature`` is supplied the app's API secret
-        is used to run the legacy verification pipeline.
-
-        :param notification_body: raw SNS notification body (the full
-            ``{"Type":"Notification", ...}`` JSON envelope, or a
-            pre-extracted ``Message`` string)
-        :param signature: optional ``X-Signature`` message attribute
-            value; when supplied, signature verification runs
-        :raises stream_chat.webhook.InvalidWebhookError: on
-            signature mismatch or any decode error
-        """
-        from stream_chat.webhook import verify_and_parse_sns
+        return parse_sqs(message_body)
+
+    def parse_sns(self, message: Union[bytes, str]) -> Dict[str, Any]:
+        """Parse an SNS body (unwraps SNS envelope when present). No HMAC."""
+
+        from stream_chat.webhook import parse_sns
 
-        if signature is None:
-            return verify_and_parse_sns(notification_body)
-        return verify_and_parse_sns(notification_body, signature, self.api_secret)
+        return parse_sns(message)
 
     @abc.abstractmethod
     def update_app_settings(