refactor(webhooks): unify webhook errors under InvalidWebhookError (CHA-3071)

Per cross-SDK coordination (mogita's review on the 6 sibling SDK PRs),
every webhook failure path now terminates at a single exception class.
Customers only need one except arm and can filter by message text for
mode-specific behaviour (signature mismatch vs invalid base64 etc.).

Renames the previously-unreleased WebhookSignatureError to
InvalidWebhookError and threads it through every primitive:

  verify_signature      -> 'signature mismatch'
  gunzip_payload        -> 'gzip decompression failed'
  decode_sqs_payload    -> 'invalid base64 encoding'
  parse_event           -> 'invalid JSON payload'

StreamChat#verify_webhook (the legacy bool helper) is untouched. The
message constants are exported so callers can exact-match if they
prefer that over substring matching.

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

Author: nijeesh-stream

docs/webhooks/webhooks_overview/webhooks_overview.md

@@ -135,7 +135,7 @@ def stream_webhook():
 
 The same call works whether or not Stream is compressing for this app, and whether or not your framework auto-decompressed the request — the helper inspects the body bytes rather than the `Content-Encoding` header.
 
-All helpers raise `stream_chat.base.exceptions.WebhookSignatureError` when the signature does not match, when the gzip stream is corrupt, or when the SQS/SNS base64 envelope cannot be decoded.
+All helpers raise `stream_chat.webhook.InvalidWebhookError` when the signature does not match, when the gzip stream is corrupt, or when the SQS/SNS base64 envelope cannot be decoded.
 
 The original `client.verify_webhook(request.body, request.headers["X-Signature"])` — which returns a `bool` and does not decompress — stays unchanged for backward compatibility. Switch to `verify_and_parse_webhook` to support compressed payloads.
 

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.webhook.InvalidWebhookError: on
             signature mismatch or any decode error
         """
         from stream_chat.webhook import verify_and_parse_webhook
@@ -167,7 +167,7 @@ def verify_and_parse_sqs(
 
         :param message_body: SQS message ``Body`` (string)
         :param signature: ``X-Signature`` message attribute value
-        :raises stream_chat.base.exceptions.WebhookSignatureError: on
+        :raises stream_chat.webhook.InvalidWebhookError: on
             signature mismatch or any decode error
         """
         from stream_chat.webhook import verify_and_parse_sqs
@@ -187,7 +187,7 @@ def verify_and_parse_sns(
 
         :param message: SNS notification ``Message`` field (string)
         :param signature: ``X-Signature`` message attribute value
-        :raises stream_chat.base.exceptions.WebhookSignatureError: on
+        :raises stream_chat.webhook.InvalidWebhookError: on
             signature mismatch or any decode error
         """
         from stream_chat.webhook import verify_and_parse_sns

stream_chat/base/exceptions.py

@@ -25,17 +25,3 @@ def __str__(self) -> str:
             return f'StreamChat error code {self.error_code}: {self.error_message}"'
         else:
             return f"StreamChat error HTTP code: {self.status_code}"
-
-
-class WebhookSignatureError(StreamAPIException):
-    """Raised when an outbound webhook signature does not match, the
-    webhook payload cannot be decompressed, or the wrapping (e.g. base64)
-    cannot be decoded.
-    """
-
-    def __init__(self, message: str) -> None:
-        super().__init__(message, status_code=0)
-        self.message = message
-
-    def __str__(self) -> str:
-        return f"WebhookSignatureError: {self.message}"

stream_chat/tests/test_webhook_compression.py

@@ -27,9 +27,9 @@
 import pytest
 
 from stream_chat import StreamChat, StreamChatAsync
-from stream_chat.base.exceptions import WebhookSignatureError
 from stream_chat.webhook import (
     GZIP_MAGIC,
+    InvalidWebhookError,
     decode_sns_payload,
     decode_sqs_payload,
     gunzip_payload,
@@ -88,9 +88,13 @@ def test_short_input_below_magic_length(self):
 
     def test_truncated_gzip_with_magic_raises(self):
         bad = GZIP_MAGIC + b"\x00\x00\x00"
-        with pytest.raises(WebhookSignatureError) as exc_info:
+        with pytest.raises(InvalidWebhookError, match=r"gzip decompression failed"):
             gunzip_payload(bad)
-        assert "decompress" in str(exc_info.value).lower()
+
+    def test_gunzip_payload_raises_on_corrupt_gzip(self):
+        corrupt = GZIP_MAGIC + b"\x08\x00" + b"\x00" * 20
+        with pytest.raises(InvalidWebhookError, match=r"gzip decompression failed"):
+            gunzip_payload(corrupt)
 
     def test_decompresses_helloworld_fixture(self):
         gz_bytes = base64.b64decode("H4sIAGrYAWoAA8tIzcnJL88vykkBAK0g6/kKAAAA")
@@ -114,9 +118,12 @@ 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, match=r"invalid base64 encoding"):
             decode_sqs_payload("!!!not-valid-base64!!!")
-        assert "base64" in str(exc_info.value).lower()
+
+    def test_decode_sqs_payload_raises_on_invalid_base64(self):
+        with pytest.raises(InvalidWebhookError, match=r"invalid base64 encoding"):
+            decode_sqs_payload("not*valid*base64*data")
 
     def test_decodes_helloworld_base64_fixture(self):
         assert decode_sqs_payload("aGVsbG93b3JsZA==") == b"helloworld"
@@ -208,8 +215,8 @@ def test_unknown_event_type_still_parses(self):
         body = b'{"type":"a.future.event","custom":42}'
         assert parse_event(body) == {"type": "a.future.event", "custom": 42}
 
-    def test_malformed_json_raises(self):
-        with pytest.raises(json.JSONDecodeError):
+    def test_parse_event_raises_on_invalid_json(self):
+        with pytest.raises(InvalidWebhookError, match=r"invalid JSON payload"):
             parse_event(b"not json")
 
 
@@ -228,29 +235,28 @@ 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, match=r"signature mismatch"):
             verify_and_parse_webhook(JSON_BODY, "0" * 64, API_SECRET)
-        assert "invalid webhook signature" in str(exc_info.value).lower()
 
     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, match=r"signature mismatch"):
             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, match=r"signature mismatch"):
             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, match=r"signature mismatch"):
             verify_and_parse_webhook(JSON_BODY, b"\xff" * 32, API_SECRET)
-        with pytest.raises(WebhookSignatureError):
+        with pytest.raises(InvalidWebhookError, match=r"signature mismatch"):
             verify_and_parse_webhook(JSON_BODY, "\u2603" * 64, API_SECRET)
 
 
@@ -267,13 +273,13 @@ def test_base64_plus_gzip(self):
 
     def test_signature_mismatch_raises(self):
         wrapped = _b64(_gzip(JSON_BODY))
-        with pytest.raises(WebhookSignatureError):
+        with pytest.raises(InvalidWebhookError, match=r"signature mismatch"):
             verify_and_parse_sqs(wrapped, "0" * 64, API_SECRET)
 
     def test_signature_over_compressed_or_wrapped_bytes_rejected(self):
         wrapped = _b64(_gzip(JSON_BODY))
         sig_over_wrapped = _sign(wrapped.encode("ascii"))
-        with pytest.raises(WebhookSignatureError):
+        with pytest.raises(InvalidWebhookError, match=r"signature mismatch"):
             verify_and_parse_sqs(wrapped, sig_over_wrapped, API_SECRET)
 
 
@@ -300,7 +306,7 @@ def test_rejects_signature_over_envelope(self):
         wrapped = _b64(_gzip(JSON_BODY))
         envelope = _sns_envelope(wrapped)
         sig_over_envelope = _sign(envelope.encode("utf-8"))
-        with pytest.raises(WebhookSignatureError):
+        with pytest.raises(InvalidWebhookError, match=r"signature mismatch"):
             verify_and_parse_sns(envelope, sig_over_envelope, API_SECRET)
 
 
@@ -320,7 +326,7 @@ def test_verify_and_parse_sns(self, sync_client: StreamChat):
         assert sync_client.verify_and_parse_sns(wrapped, sig) == EVENT_DICT
 
     def test_signature_mismatch_via_client(self, sync_client: StreamChat):
-        with pytest.raises(WebhookSignatureError):
+        with pytest.raises(InvalidWebhookError, match=r"signature mismatch"):
             sync_client.verify_and_parse_webhook(JSON_BODY, "0" * 64)
 
 

stream_chat/webhook.py

@@ -19,12 +19,33 @@
 import hashlib
 import hmac
 import json
+import zlib
 from typing import Any, Dict, Optional, Union
 
-from stream_chat.base.exceptions import WebhookSignatureError
-
 GZIP_MAGIC = b"\x1f\x8b"
 
+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 InvalidWebhookError(Exception):
+    """Raised by every webhook primitive when verification or decoding
+    fails. The cross-SDK contract is "one exception, message says why" -
+    callers branch on the message text when they need mode-specific
+    behaviour (signature mismatch vs invalid base64 vs corrupt gzip vs
+    malformed JSON).
+    """
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+    def __str__(self) -> str:
+        return f"InvalidWebhookError: {self.message}"
+
+
 _BytesLike = Union[bytes, bytearray, memoryview, str]
 
 
@@ -49,8 +70,8 @@ def gunzip_payload(body: _BytesLike) -> bytes:
         return raw
     try:
         return gzip.decompress(raw)
-    except (gzip.BadGzipFile, OSError, EOFError) as exc:
-        raise WebhookSignatureError(f"failed to decompress gzip payload: {exc}")
+    except (gzip.BadGzipFile, OSError, EOFError, zlib.error) as err:
+        raise InvalidWebhookError(INVALID_WEBHOOK_GZIP_FAILED) from err
 
 
 def decode_sqs_payload(body: _BytesLike) -> bytes:
@@ -65,8 +86,8 @@ def decode_sqs_payload(body: _BytesLike) -> bytes:
     raw = _to_bytes(body)
     try:
         decoded = base64.b64decode(raw, validate=True)
-    except ValueError as exc:
-        raise WebhookSignatureError(f"failed to base64-decode payload: {exc}")
+    except ValueError as err:
+        raise InvalidWebhookError(INVALID_WEBHOOK_INVALID_BASE64) from err
     return gunzip_payload(decoded)
 
 
@@ -141,8 +162,11 @@ def parse_event(payload: _BytesLike) -> Dict[str, Any]:
     without changing call sites.
     """
     if isinstance(payload, (bytes, bytearray, memoryview)):
-        return json.loads(bytes(payload))
-    return json.loads(payload)
+        payload = bytes(payload)
+    try:
+        return json.loads(payload)
+    except json.JSONDecodeError as err:
+        raise InvalidWebhookError(INVALID_WEBHOOK_INVALID_JSON) from err
 
 
 def _verify_and_parse(
@@ -151,7 +175,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)
 
 
@@ -166,7 +190,7 @@ 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 any decode error
     """
     inflated = gunzip_payload(body)
     return _verify_and_parse(inflated, signature, secret)