feat(webhooks): align cross-SDK contract — InvalidWebhookError + gunzip_payload

- Rename WebhookSignatureError → InvalidWebhookError
- Rename ungzip_payload → gunzip_payload
- Align error messages to documented strings: signature mismatch /
  invalid base64 encoding / gzip decompression failed / invalid JSON payload
- parse_event now wraps json.JSONDecodeError as InvalidWebhookError
- Export INVALID_WEBHOOK_* constants for exact-match filtering

Author: nijeesh-stream

stream_chat/base/client.py

@@ -147,7 +147,7 @@ def verify_and_parse_webhook(
 
         :param body: raw HTTP request body bytes Stream signed
         :param signature: ``X-Signature`` header value
-        :raises stream_chat.base.exceptions.WebhookSignatureError: on
+        :raises stream_chat.base.exceptions.InvalidWebhookError: on
             signature mismatch or any decode error
         """
         from stream_chat.webhook import verify_and_parse_webhook

stream_chat/base/exceptions.py

@@ -6,8 +6,21 @@ class StreamChannelException(Exception):
     pass
 
 
-class WebhookSignatureError(Exception):
-    """Invalid webhook signature or malformed gzip/base64 envelope."""
+class InvalidWebhookError(Exception):
+    """Invalid webhook signature or malformed gzip/base64/JSON envelope.
+
+    Raised by :mod:`stream_chat.webhook` on any failure path: signature
+    mismatch, malformed base64, gzip decompression failure, or invalid
+    JSON payload. The message text identifies the failure mode so
+    callers that want to differentiate (security logging, retry policy)
+    can filter on substring or on the module-level constants.
+    """
+
+
+INVALID_WEBHOOK_SIGNATURE_MISMATCH = "signature mismatch"
+INVALID_WEBHOOK_INVALID_BASE64 = "invalid base64 encoding"
+INVALID_WEBHOOK_GZIP_FAILED = "gzip decompression failed"
+INVALID_WEBHOOK_INVALID_JSON = "invalid JSON payload"
 
 
 class StreamAPIException(Exception):

stream_chat/tests/test_webhook_compression.py

@@ -4,7 +4,7 @@
 
 * Module-level functions in :mod:`stream_chat.webhook`:
 
-  * primitives - ``ungzip_payload``, ``decode_sqs_payload``,
+  * primitives - ``gunzip_payload``, ``decode_sqs_payload``,
     ``decode_sns_payload``, ``verify_signature``, ``parse_event``
   * composite helpers - ``verify_and_parse_webhook``, ``parse_sqs``,
     ``parse_sns``
@@ -27,15 +27,21 @@
 import pytest
 
 from stream_chat import StreamChat, StreamChatAsync
-from stream_chat.base.exceptions import WebhookSignatureError
+from stream_chat.base.exceptions import (
+    INVALID_WEBHOOK_GZIP_FAILED,
+    INVALID_WEBHOOK_INVALID_BASE64,
+    INVALID_WEBHOOK_INVALID_JSON,
+    INVALID_WEBHOOK_SIGNATURE_MISMATCH,
+    InvalidWebhookError,
+)
 from stream_chat.webhook import (
     GZIP_MAGIC,
     decode_sns_payload,
     decode_sqs_payload,
+    gunzip_payload,
     parse_event,
     parse_sns,
     parse_sqs,
-    ungzip_payload,
     verify_and_parse_webhook,
     verify_signature,
 )
@@ -66,31 +72,31 @@ def sync_client() -> StreamChat:
     return StreamChat(api_key=API_KEY, api_secret=API_SECRET)
 
 
-class TestUngzipPayload:
+class TestGunzipPayload:
     def test_passthrough_plain_bytes(self):
-        assert ungzip_payload(JSON_BODY) == JSON_BODY
+        assert gunzip_payload(JSON_BODY) == JSON_BODY
 
     def test_passthrough_str_input(self):
-        assert ungzip_payload(JSON_BODY.decode("utf-8")) == JSON_BODY
+        assert gunzip_payload(JSON_BODY.decode("utf-8")) == JSON_BODY
 
     def test_inflates_gzip_bytes(self):
-        assert ungzip_payload(_gzip(JSON_BODY)) == JSON_BODY
+        assert gunzip_payload(_gzip(JSON_BODY)) == JSON_BODY
 
     def test_returns_bytes(self):
-        assert isinstance(ungzip_payload(JSON_BODY), bytes)
-        assert isinstance(ungzip_payload(_gzip(JSON_BODY)), bytes)
+        assert isinstance(gunzip_payload(JSON_BODY), bytes)
+        assert isinstance(gunzip_payload(_gzip(JSON_BODY)), bytes)
 
     def test_empty_input(self):
-        assert ungzip_payload(b"") == b""
+        assert gunzip_payload(b"") == b""
 
     def test_short_input_below_magic_length(self):
-        assert ungzip_payload(b"ab") == b"ab"
+        assert gunzip_payload(b"ab") == b"ab"
 
     def test_truncated_gzip_with_magic_raises(self):
         bad = GZIP_MAGIC + b"\x00\x00\x00"
-        with pytest.raises(WebhookSignatureError) as exc_info:
-            ungzip_payload(bad)
-        assert "decompress" in str(exc_info.value).lower()
+        with pytest.raises(InvalidWebhookError) as exc_info:
+            gunzip_payload(bad)
+        assert str(exc_info.value) == INVALID_WEBHOOK_GZIP_FAILED
 
 
 class TestDecodeSqsPayload:
@@ -110,9 +116,9 @@ def test_accepts_bytes_input(self):
         assert decode_sqs_payload(encoded) == JSON_BODY
 
     def test_invalid_base64_raises(self):
-        with pytest.raises(WebhookSignatureError) as exc_info:
+        with pytest.raises(InvalidWebhookError) as exc_info:
             decode_sqs_payload("!!!not-valid-base64!!!")
-        assert "base64" in str(exc_info.value).lower()
+        assert str(exc_info.value) == INVALID_WEBHOOK_INVALID_BASE64
 
 
 def _sns_envelope(inner_message: str) -> str:
@@ -178,7 +184,7 @@ def test_non_ascii_bytes_signature_returns_false(self):
         assert verify_signature(JSON_BODY, b"\xff" * 32, API_SECRET) is False
 
     def test_non_ascii_str_signature_returns_false(self):
-        assert verify_signature(JSON_BODY, "\u2603" * 64, API_SECRET) is False
+        assert verify_signature(JSON_BODY, "☃" * 64, API_SECRET) is False
 
     def test_non_string_signature_returns_false(self):
         assert verify_signature(JSON_BODY, 12345, API_SECRET) is False  # type: ignore[arg-type]
@@ -196,8 +202,9 @@ def test_unknown_event_type_still_parses(self):
         assert parse_event(body) == {"type": "a.future.event", "custom": 42}
 
     def test_malformed_json_raises(self):
-        with pytest.raises(json.JSONDecodeError):
+        with pytest.raises(InvalidWebhookError) as exc_info:
             parse_event(b"not json")
+        assert str(exc_info.value) == INVALID_WEBHOOK_INVALID_JSON
 
 
 class TestVerifyAndParseWebhook:
@@ -215,30 +222,30 @@ def test_returns_dict(self):
         assert isinstance(result, dict)
 
     def test_signature_mismatch_raises(self):
-        with pytest.raises(WebhookSignatureError) as exc_info:
+        with pytest.raises(InvalidWebhookError) as exc_info:
             verify_and_parse_webhook(JSON_BODY, "0" * 64, API_SECRET)
-        assert "invalid webhook signature" in str(exc_info.value).lower()
+        assert str(exc_info.value) == INVALID_WEBHOOK_SIGNATURE_MISMATCH
 
     def test_signature_must_be_over_uncompressed_bytes(self):
         compressed = _gzip(JSON_BODY)
         sig_over_compressed = _sign(compressed)
-        with pytest.raises(WebhookSignatureError):
+        with pytest.raises(InvalidWebhookError):
             verify_and_parse_webhook(compressed, sig_over_compressed, API_SECRET)
 
     def test_wrong_secret_raises(self):
         sig = _sign(JSON_BODY, secret="other")
-        with pytest.raises(WebhookSignatureError):
+        with pytest.raises(InvalidWebhookError):
             verify_and_parse_webhook(JSON_BODY, sig, API_SECRET)
 
     def test_signature_can_be_bytes(self):
         sig = _sign(JSON_BODY).encode()
         assert verify_and_parse_webhook(JSON_BODY, sig, API_SECRET) == EVENT_DICT
 
     def test_malformed_signature_surfaces_as_webhook_error(self):
-        with pytest.raises(WebhookSignatureError):
+        with pytest.raises(InvalidWebhookError):
             verify_and_parse_webhook(JSON_BODY, b"\xff" * 32, API_SECRET)
-        with pytest.raises(WebhookSignatureError):
-            verify_and_parse_webhook(JSON_BODY, "\u2603" * 64, API_SECRET)
+        with pytest.raises(InvalidWebhookError):
+            verify_and_parse_webhook(JSON_BODY, "☃" * 64, API_SECRET)
 
 
 class TestParseSqs:
@@ -280,7 +287,7 @@ def test_parse_sns(self, sync_client: StreamChat):
         assert sync_client.parse_sns(wrapped) == EVENT_DICT
 
     def test_signature_mismatch_via_client(self, sync_client: StreamChat):
-        with pytest.raises(WebhookSignatureError):
+        with pytest.raises(InvalidWebhookError):
             sync_client.verify_and_parse_webhook(JSON_BODY, "0" * 64)
 
 

stream_chat/webhook.py

@@ -20,7 +20,13 @@
 import json
 from typing import Any, Dict, Optional, Union
 
-from stream_chat.base.exceptions import WebhookSignatureError
+from stream_chat.base.exceptions import (
+    INVALID_WEBHOOK_GZIP_FAILED,
+    INVALID_WEBHOOK_INVALID_BASE64,
+    INVALID_WEBHOOK_INVALID_JSON,
+    INVALID_WEBHOOK_SIGNATURE_MISMATCH,
+    InvalidWebhookError,
+)
 
 GZIP_MAGIC = b"\x1f\x8b"
 
@@ -35,7 +41,7 @@ def _to_bytes(body: _BytesLike) -> bytes:
     raise TypeError(f"webhook body must be bytes or str, got {type(body).__name__}")
 
 
-def ungzip_payload(body: _BytesLike) -> bytes:
+def gunzip_payload(body: _BytesLike) -> bytes:
     """Return ``body`` unchanged unless it starts with the gzip magic
     (``1f 8b``, per RFC 1952), in which case the gzip stream is decompressed.
 
@@ -49,7 +55,7 @@ def ungzip_payload(body: _BytesLike) -> bytes:
     try:
         return gzip.decompress(raw)
     except (gzip.BadGzipFile, OSError, EOFError) as exc:
-        raise WebhookSignatureError(f"failed to decompress gzip payload: {exc}")
+        raise InvalidWebhookError(INVALID_WEBHOOK_GZIP_FAILED) from exc
 
 
 def decode_sqs_payload(body: _BytesLike) -> bytes:
@@ -65,8 +71,8 @@ def decode_sqs_payload(body: _BytesLike) -> bytes:
     try:
         decoded = base64.b64decode(raw, validate=True)
     except ValueError as exc:
-        raise WebhookSignatureError(f"failed to base64-decode payload: {exc}")
-    return ungzip_payload(decoded)
+        raise InvalidWebhookError(INVALID_WEBHOOK_INVALID_BASE64) from exc
+    return gunzip_payload(decoded)
 
 
 def decode_sns_payload(notification_body: _BytesLike) -> bytes:
@@ -139,9 +145,12 @@ def parse_event(payload: _BytesLike) -> Dict[str, Any]:
     documented primitive so callers can swap in a typed parser later
     without changing call sites.
     """
-    if isinstance(payload, (bytes, bytearray, memoryview)):
-        return json.loads(bytes(payload))
-    return json.loads(payload)
+    try:
+        if isinstance(payload, (bytes, bytearray, memoryview)):
+            return json.loads(bytes(payload))
+        return json.loads(payload)
+    except (json.JSONDecodeError, ValueError) as exc:
+        raise InvalidWebhookError(INVALID_WEBHOOK_INVALID_JSON) from exc
 
 
 def _verify_and_parse(
@@ -150,7 +159,7 @@ def _verify_and_parse(
     secret: str,
 ) -> Dict[str, Any]:
     if not verify_signature(payload_bytes, signature, secret):
-        raise WebhookSignatureError("invalid webhook signature")
+        raise InvalidWebhookError(INVALID_WEBHOOK_SIGNATURE_MISMATCH)
     return parse_event(payload_bytes)
 
 
@@ -165,9 +174,9 @@ def verify_and_parse_webhook(
     :param body: raw HTTP request body bytes Stream signed
     :param signature: ``X-Signature`` header value
     :param secret: the app's API secret
-    :raises WebhookSignatureError: on signature mismatch or decode error
+    :raises InvalidWebhookError: on signature mismatch or decode error
     """
-    inflated = ungzip_payload(body)
+    inflated = gunzip_payload(body)
     return _verify_and_parse(inflated, signature, secret)