feat(webhooks): make signature optional on verify_and_parse_sqs/sns (CHA-3071)

Stream does not ship an X-Signature on SQS or SNS deliveries — those
transports ride AWS-internal infrastructure (IAM-authenticated queues
and AWS-signed SNS notifications), so HMAC verification on top is
theatre. signature + secret are now optional on both module helpers
and on the StreamChat / StreamChatAsync instance methods.

- verify_and_parse_sqs(body)                -> decode + parse
- verify_and_parse_sqs(body, sig, secret)   -> decode + verify + parse
- verify_and_parse_sns(envelope_body)       -> unwrap + decode + parse
- verify_and_parse_sns(envelope_body, sig, secret) -> + verify

Passing only one of (signature, secret) raises InvalidWebhookError.
The HTTP-webhook path (verify_and_parse_webhook) is unchanged.

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

Author: nijeesh-stream

docs/webhooks/webhooks_overview/webhooks_overview.md

@@ -141,42 +141,49 @@ The original `client.verify_webhook(request.body, request.headers["X-Signature"]
 
 #### SQS / SNS firehose
 
-For events delivered through SQS or SNS, call the matching helper. It base64-decodes the envelope, gzip-decompresses when the magic bytes are present, verifies the HMAC, and returns the parsed event.
+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.
 
 For SQS, pass the message `Body` (already the payload):
 
 ```python
-event = client.verify_and_parse_sqs(
-    sqs_message["Body"],
-    sqs_message["MessageAttributes"]["X-Signature"]["StringValue"],
-)
+event = client.verify_and_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
-import json
-
 # Django SNS HTTP delivery
-attrs = json.loads(request.body)["MessageAttributes"]
-event = client.verify_and_parse_sns(
-    request.body,                                # raw envelope (bytes/str)
-    attrs["X-Signature"]["Value"],
-)
+event = client.verify_and_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. They take the API secret as a third argument and are otherwise identical:
+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:
 
 ```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)
 ```
 
+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` |
+| ------------------- | -------------------------- | ---------------------- | ---------------------- |
+| body / message_body / notification_body | required | required | required |
+| signature           | required                   | optional               | optional               |
+| secret              | required                   | optional               | optional               |
+
 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.
 
 All webhook requests contain these headers:

stream_chat/base/client.py

@@ -157,42 +157,58 @@ def verify_and_parse_webhook(
     def verify_and_parse_sqs(
         self,
         message_body: Union[bytes, str],
-        signature: Union[str, bytes],
+        signature: Optional[Union[str, bytes]] = None,
     ) -> Dict[str, Any]:
-        """Verify and parse an SQS firehose webhook event.
+        """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.
+        ``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: ``X-Signature`` message attribute value
+        :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
 
+        if signature is None:
+            return verify_and_parse_sqs(message_body)
         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],
+        notification_body: Union[bytes, str],
+        signature: Optional[Union[str, bytes]] = None,
     ) -> Dict[str, Any]:
-        """Verify and parse an SNS firehose webhook event.
+        """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
+        ``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 verify_and_parse_sns(message, signature, self.api_secret)
+        if signature is None:
+            return verify_and_parse_sns(notification_body)
+        return verify_and_parse_sns(notification_body, signature, self.api_secret)
 
     @abc.abstractmethod
     def update_app_settings(

stream_chat/tests/test_webhook_compression.py

@@ -282,6 +282,24 @@ def test_signature_over_compressed_or_wrapped_bytes_rejected(self):
         with pytest.raises(InvalidWebhookError, match=r"signature mismatch"):
             verify_and_parse_sqs(wrapped, sig_over_wrapped, API_SECRET)
 
+    def test_verify_and_parse_sqs_without_signature_parses(self):
+        assert verify_and_parse_sqs(_b64(JSON_BODY)) == EVENT_DICT
+        assert verify_and_parse_sqs(_b64(_gzip(JSON_BODY))) == EVENT_DICT
+        assert verify_and_parse_sqs(_b64(_gzip(JSON_BODY)).encode()) == EVENT_DICT
+
+    def test_static_verify_and_parse_sqs_raises_on_partial_creds(self):
+        wrapped = _b64(_gzip(JSON_BODY))
+        with pytest.raises(
+            InvalidWebhookError,
+            match=r"signature and secret must both be provided",
+        ):
+            verify_and_parse_sqs(wrapped, _sign(JSON_BODY))
+        with pytest.raises(
+            InvalidWebhookError,
+            match=r"signature and secret must both be provided",
+        ):
+            verify_and_parse_sqs(wrapped, secret=API_SECRET)
+
 
 class TestVerifyAndParseSns:
     def test_pre_extracted_message_round_trip(self):
@@ -309,6 +327,13 @@ def test_rejects_signature_over_envelope(self):
         with pytest.raises(InvalidWebhookError, match=r"signature mismatch"):
             verify_and_parse_sns(envelope, sig_over_envelope, API_SECRET)
 
+    def test_verify_and_parse_sns_without_signature_parses(self):
+        wrapped = _b64(_gzip(JSON_BODY))
+        envelope = _sns_envelope(wrapped)
+        assert verify_and_parse_sns(envelope) == EVENT_DICT
+        assert verify_and_parse_sns(wrapped) == EVENT_DICT
+        assert verify_and_parse_sns(_b64(JSON_BODY)) == EVENT_DICT
+
 
 class TestSyncClientMethods:
     def test_verify_and_parse_webhook(self, sync_client: StreamChat):
@@ -329,6 +354,13 @@ def test_signature_mismatch_via_client(self, sync_client: StreamChat):
         with pytest.raises(InvalidWebhookError, match=r"signature mismatch"):
             sync_client.verify_and_parse_webhook(JSON_BODY, "0" * 64)
 
+    def test_instance_verify_and_parse_sqs_without_signature(self):
+        client = StreamChat(api_key=API_KEY, api_secret="")
+        wrapped = _b64(_gzip(JSON_BODY))
+        envelope = _sns_envelope(wrapped)
+        assert client.verify_and_parse_sqs(wrapped) == EVENT_DICT
+        assert client.verify_and_parse_sns(envelope) == EVENT_DICT
+
 
 class TestSyncClientLegacyVerifyWebhook:
     """The legacy boolean helper stays unchanged for backward compatibility."""

stream_chat/webhook.py

@@ -28,6 +28,9 @@
 INVALID_WEBHOOK_INVALID_BASE64 = "invalid base64 encoding"
 INVALID_WEBHOOK_GZIP_FAILED = "gzip decompression failed"
 INVALID_WEBHOOK_INVALID_JSON = "invalid JSON payload"
+INVALID_WEBHOOK_PARTIAL_AWS_CREDS = (
+    "signature and secret must both be provided to verify the SQS/SNS payload"
+)
 
 
 class InvalidWebhookError(Exception):
@@ -179,6 +182,18 @@ def _verify_and_parse(
     return parse_event(payload_bytes)
 
 
+def _maybe_verify_and_parse(
+    payload_bytes: bytes,
+    signature: Optional[Union[str, bytes]],
+    secret: Optional[str],
+) -> Dict[str, Any]:
+    if not signature and not secret:
+        return parse_event(payload_bytes)
+    if not signature or not secret:
+        raise InvalidWebhookError(INVALID_WEBHOOK_PARTIAL_AWS_CREDS)
+    return _verify_and_parse(payload_bytes, signature, secret)
+
+
 def verify_and_parse_webhook(
     body: _BytesLike,
     signature: Union[str, bytes],
@@ -198,25 +213,51 @@ def verify_and_parse_webhook(
 
 def verify_and_parse_sqs(
     message_body: _BytesLike,
-    signature: Union[str, bytes],
-    secret: str,
+    signature: Optional[Union[str, bytes]] = None,
+    secret: Optional[str] = None,
 ) -> Dict[str, Any]:
-    """Decode the SQS ``Body`` (base64, then gzip-if-magic), verify the
-    HMAC ``signature`` from the ``X-Signature`` message attribute, and
-    return the parsed event.
+    """Decode the SQS ``Body`` (base64, then gzip-if-magic) and return
+    the parsed event.
+
+    Stream does not attach an ``X-Signature`` to SQS deliveries: the
+    transport is an IAM-authenticated AWS queue, so the queue ARN
+    already proves origin. HMAC verification on top is redundant and
+    is therefore optional. When ``signature`` and ``secret`` are both
+    supplied the legacy verification pipeline still runs, so existing
+    callers keep working unchanged.
+
+    :param message_body: SQS message ``Body`` (string)
+    :param signature: optional ``X-Signature`` message attribute value
+    :param secret: optional API secret matching ``signature``
+    :raises InvalidWebhookError: on signature mismatch, any decode
+        error, or when only one of ``signature`` / ``secret`` is given
     """
     inflated = decode_sqs_payload(message_body)
-    return _verify_and_parse(inflated, signature, secret)
+    return _maybe_verify_and_parse(inflated, signature, secret)
 
 
 def verify_and_parse_sns(
-    message: _BytesLike,
-    signature: Union[str, bytes],
-    secret: str,
+    notification_body: _BytesLike,
+    signature: Optional[Union[str, bytes]] = None,
+    secret: Optional[str] = None,
 ) -> Dict[str, Any]:
-    """Decode the SNS ``Message`` (identical to SQS handling), verify
-    the HMAC ``signature`` from the ``X-Signature`` message attribute,
-    and return the parsed event.
+    """Decode the SNS ``Message`` (identical to SQS handling) and return
+    the parsed event.
+
+    Stream does not attach an ``X-Signature`` to SNS deliveries: AWS
+    already signs the SNS notification envelope, so verifying that the
+    request really came from your topic happens at the SNS layer.
+    HMAC verification on top is optional. When ``signature`` and
+    ``secret`` are both supplied the legacy verification pipeline still
+    runs, so existing callers keep working unchanged.
+
+    :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
+    :param secret: optional API secret matching ``signature``
+    :raises InvalidWebhookError: on signature mismatch, any decode
+        error, or when only one of ``signature`` / ``secret`` is given
     """
-    inflated = decode_sns_payload(message)
-    return _verify_and_parse(inflated, signature, secret)
+    inflated = decode_sns_payload(notification_body)
+    return _maybe_verify_and_parse(inflated, signature, secret)