algovoi-webhook-verifier 0.1.0__tar.gz

algovoi_webhook_verifier-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.eggs/
+.pytest_cache/
+*.pyc
+
+# TypeScript / Node
+node_modules/
+typescript/dist/
+typescript/node_modules/
+*.tsbuildinfo
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

algovoi_webhook_verifier-0.1.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: algovoi-webhook-verifier
+Version: 0.1.0
+Summary: Cryptographic verifier for AlgoVoi webhook signatures (v1 HMAC-SHA256 + v2 HKDF-SHA256/HMAC-SHA384)
+Project-URL: Homepage, https://docs.algovoi.co.uk/webhook-verifier
+Project-URL: Repository, https://github.com/chopmob-cloud/algovoi-webhook-verifier
+Project-URL: Bug Tracker, https://github.com/chopmob-cloud/algovoi-webhook-verifier/issues
+Author-email: AlgoVoi <dev@algovoi.co.uk>
+License: Apache-2.0
+Keywords: algovoi,hmac,signature,verification,webhook
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: cryptography>=41.0.0
+Description-Content-Type: text/markdown
+
+See the [repository README](https://github.com/chopmob-cloud/algovoi-webhook-verifier) for full documentation.

algovoi_webhook_verifier-0.1.0/README.md

@@ -0,0 +1 @@
+See the [repository README](https://github.com/chopmob-cloud/algovoi-webhook-verifier) for full documentation.

algovoi_webhook_verifier-0.1.0/algovoi_webhook_verifier/__init__.py

@@ -0,0 +1,16 @@
+"""AlgoVoi webhook verifier — public API."""
+
+from .errors import ERROR_CODES, ErrorCode, WebhookVerificationError
+from .verify import DEFAULT_TOLERANCE, KNOWN_EVENT_TYPES, SIGNATURE_HEADER, verify_webhook
+
+__all__ = [
+    "verify_webhook",
+    "WebhookVerificationError",
+    "ErrorCode",
+    "ERROR_CODES",
+    "SIGNATURE_HEADER",
+    "DEFAULT_TOLERANCE",
+    "KNOWN_EVENT_TYPES",
+]
+
+__version__ = "0.1.0"

algovoi_webhook_verifier-0.1.0/algovoi_webhook_verifier/errors.py

@@ -0,0 +1,40 @@
+"""Typed error codes for AlgoVoi webhook verification failures."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+ERROR_CODES = frozenset({
+    "MISSING_SIGNATURE",
+    "MALFORMED_SIGNATURE",
+    "STALE_SIGNATURE",
+    "INVALID_SIGNATURE",
+    "INVALID_PAYLOAD",
+    "UNKNOWN_EVENT_TYPE",
+})
+
+ErrorCode = Literal[
+    "MISSING_SIGNATURE",
+    "MALFORMED_SIGNATURE",
+    "STALE_SIGNATURE",
+    "INVALID_SIGNATURE",
+    "INVALID_PAYLOAD",
+    "UNKNOWN_EVENT_TYPE",
+]
+
+
+class WebhookVerificationError(Exception):
+    """Raised when webhook signature verification fails.
+
+    Attributes:
+        code:    One of the six ``ERROR_CODES`` values.
+        message: Human-readable description.
+    """
+
+    def __init__(self, code: ErrorCode, message: str) -> None:
+        super().__init__(message)
+        self.code: ErrorCode = code
+        self.message: str = message
+
+    def __repr__(self) -> str:
+        return f"WebhookVerificationError(code={self.code!r}, message={self.message!r})"

algovoi_webhook_verifier-0.1.0/algovoi_webhook_verifier/verify.py

@@ -0,0 +1,171 @@
+"""AlgoVoi webhook signature verifier — v1 (HMAC-SHA256) and v2 (HKDF-SHA256 + HMAC-SHA384)."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import re
+import time
+from typing import Any
+
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+from .errors import WebhookVerificationError
+
+# Header name used by the AlgoVoi gateway
+SIGNATURE_HEADER = "X-AlgoVoi-Signature"
+
+# Default replay-prevention window (seconds)
+DEFAULT_TOLERANCE = 300
+
+# Supported event types
+KNOWN_EVENT_TYPES = frozenset({"payment.confirmed"})
+
+_SIG_RE = re.compile(
+    r"^t=(?P<ts>\d+),v1=(?P<v1>[0-9a-f]{64})(?:,v2=(?P<v2>[0-9a-f]{96}))?$"
+)
+
+
+def _derive_v2_key(secret_bytes: bytes) -> bytes:
+    """HKDF-SHA256 key derivation matching the gateway _sign() implementation."""
+    hkdf = HKDF(
+        algorithm=hashes.SHA256(),
+        length=48,
+        salt=b"algovoi-webhook-v2-pqc",
+        info=b"hmac-sha384-outbound",
+    )
+    return hkdf.derive(secret_bytes)
+
+
+def _compute_sigs(secret: str, ts: int, body: bytes) -> tuple[str, str]:
+    """Return (v1_hex, v2_hex) for the given secret, timestamp, and body."""
+    secret_bytes = secret.encode()
+    signed_payload = f"{ts}.".encode() + body
+    v1 = hmac.new(secret_bytes, signed_payload, hashlib.sha256).hexdigest()
+    v2_key = _derive_v2_key(secret_bytes)
+    v2 = hmac.new(v2_key, signed_payload, hashlib.sha384).hexdigest()
+    return v1, v2
+
+
+def verify_webhook(
+    *,
+    payload: bytes,
+    secret: str,
+    signature_header: str,
+    tolerance: int = DEFAULT_TOLERANCE,
+    require_v2: bool = False,
+) -> dict[str, Any]:
+    """Verify an AlgoVoi webhook signature and return the parsed event payload.
+
+    Parameters
+    ----------
+    payload:
+        The raw request body bytes exactly as received (do not decode first).
+    secret:
+        The webhook signing secret for the tenant (``algvw_*`` prefixed string).
+    signature_header:
+        The value of the ``X-AlgoVoi-Signature`` header.
+    tolerance:
+        Maximum age (seconds) of a valid signature. Default 300. Pass ``0``
+        to disable staleness checking (test environments only).
+    require_v2:
+        If ``True`` the v2 component *must* be present and valid.  Default
+        ``False`` (v2 is validated when present; absent v2 is accepted).
+
+    Returns
+    -------
+    dict
+        The parsed JSON event object.
+
+    Raises
+    ------
+    WebhookVerificationError
+        On any verification failure.  Inspect ``.code`` for the specific
+        failure mode.
+    """
+    # ------------------------------------------------------------------ #
+    # 1. Presence check                                                    #
+    # ------------------------------------------------------------------ #
+    trimmed_header = signature_header.strip() if signature_header else ""
+    if not trimmed_header:
+        raise WebhookVerificationError(
+            "MISSING_SIGNATURE",
+            "X-AlgoVoi-Signature header is absent",
+        )
+
+    # ------------------------------------------------------------------ #
+    # 2. Parse header                                                      #
+    # ------------------------------------------------------------------ #
+    m = _SIG_RE.match(trimmed_header)
+    if not m:
+        raise WebhookVerificationError(
+            "MALFORMED_SIGNATURE",
+            f"Signature header does not match expected format t=<unix>,v1=<sha256hex>[,v2=<sha384hex>]: {signature_header!r}",
+        )
+
+    ts = int(m.group("ts"))
+    received_v1: str = m.group("v1")
+    received_v2: str | None = m.group("v2")
+
+    # ------------------------------------------------------------------ #
+    # 3. Staleness check                                                   #
+    # ------------------------------------------------------------------ #
+    if tolerance > 0:
+        age = abs(int(time.time()) - ts)
+        if age > tolerance:
+            raise WebhookVerificationError(
+                "STALE_SIGNATURE",
+                f"Signature timestamp {ts} is {age}s old (tolerance {tolerance}s)",
+            )
+
+    # ------------------------------------------------------------------ #
+    # 4. HMAC computation                                                  #
+    # ------------------------------------------------------------------ #
+    expected_v1, expected_v2 = _compute_sigs(secret, ts, payload)
+
+    # ------------------------------------------------------------------ #
+    # 5. Signature comparison                                              #
+    # ------------------------------------------------------------------ #
+    v1_ok = hmac.compare_digest(received_v1, expected_v1)
+
+    if received_v2 is not None:
+        v2_ok = hmac.compare_digest(received_v2, expected_v2)
+    else:
+        v2_ok = not require_v2  # absent v2 is fine unless caller requires it
+
+    if not v1_ok or not v2_ok:
+        raise WebhookVerificationError(
+            "INVALID_SIGNATURE",
+            "One or more signature components did not match",
+        )
+
+    # ------------------------------------------------------------------ #
+    # 6. Payload parse                                                     #
+    # ------------------------------------------------------------------ #
+    try:
+        event: dict[str, Any] = json.loads(payload)
+    except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise WebhookVerificationError(
+            "INVALID_PAYLOAD",
+            f"Payload is not valid JSON: {exc}",
+        ) from exc
+
+    if not isinstance(event, dict):
+        raise WebhookVerificationError(
+            "INVALID_PAYLOAD",
+            "Payload root must be a JSON object",
+        )
+
+    # ------------------------------------------------------------------ #
+    # 7. Event-type check                                                  #
+    # ------------------------------------------------------------------ #
+    event_type = event.get("type")
+    if event_type not in KNOWN_EVENT_TYPES:
+        raise WebhookVerificationError(
+            "UNKNOWN_EVENT_TYPE",
+            f"Unrecognised event type: {event_type!r}",
+        )
+
+    return event

algovoi_webhook_verifier-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "algovoi-webhook-verifier"
+version = "0.1.0"
+description = "Cryptographic verifier for AlgoVoi webhook signatures (v1 HMAC-SHA256 + v2 HKDF-SHA256/HMAC-SHA384)"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.9"
+authors = [{ name = "AlgoVoi", email = "dev@algovoi.co.uk" }]
+keywords = ["webhook", "hmac", "signature", "verification", "algovoi"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security :: Cryptography",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "cryptography>=41.0.0",
+]
+
+[project.urls]
+Homepage = "https://docs.algovoi.co.uk/webhook-verifier"
+Repository = "https://github.com/chopmob-cloud/algovoi-webhook-verifier"
+"Bug Tracker" = "https://github.com/chopmob-cloud/algovoi-webhook-verifier/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["algovoi_webhook_verifier"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

algovoi_webhook_verifier-0.1.0/tests/test_vectors.py

@@ -0,0 +1,72 @@
+"""Cross-validation vector tests for algovoi_webhook_verifier."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from algovoi_webhook_verifier import WebhookVerificationError, verify_webhook
+
+VECTORS_ROOT = Path(__file__).parent.parent.parent / "vectors"
+
+
+def _load_vectors(subdir: str):
+    d = VECTORS_ROOT / subdir
+    if not d.exists():
+        pytest.skip(f"Vector directory not found: {d}")
+    return sorted(d.glob("*.json"))
+
+
+# --------------------------------------------------------------------------- #
+# Valid vectors — must all succeed                                             #
+# --------------------------------------------------------------------------- #
+
+@pytest.mark.parametrize("fixture_path", _load_vectors("valid"))
+def test_valid_vector(fixture_path):
+    fixture = json.loads(fixture_path.read_text(encoding="utf-8"))
+    body = fixture["body"].encode("utf-8")
+    event = verify_webhook(
+        payload=body,
+        secret=fixture["secret"],
+        signature_header=fixture["signature_header"],
+        tolerance=0,  # vectors use fixed timestamps — disable staleness check
+    )
+    assert event["type"] == "payment.confirmed"
+
+
+# --------------------------------------------------------------------------- #
+# Invalid vectors — must raise with matching error_code                       #
+# --------------------------------------------------------------------------- #
+
+@pytest.mark.parametrize("fixture_path", _load_vectors("invalid"))
+def test_invalid_vector(fixture_path):
+    fixture = json.loads(fixture_path.read_text(encoding="utf-8"))
+    body = fixture["body"].encode("utf-8")
+    tolerance = fixture.get("tolerance", 0)
+    fake_now = fixture.get("fake_now")
+
+    expected_code = fixture["error_code"]
+
+    def _run():
+        verify_webhook(
+            payload=body,
+            secret=fixture["secret"],
+            signature_header=fixture["signature_header"],
+            tolerance=tolerance,
+        )
+
+    with pytest.raises(WebhookVerificationError) as exc_info:
+        if fake_now is not None:
+            with patch("algovoi_webhook_verifier.verify.time") as mock_time:
+                mock_time.time.return_value = fake_now
+                _run()
+        else:
+            _run()
+
+    assert exc_info.value.code == expected_code, (
+        f"Vector {fixture_path.name}: expected error code {expected_code!r}, "
+        f"got {exc_info.value.code!r}"
+    )

algovoi_webhook_verifier-0.1.0/tests/test_verify.py

@@ -0,0 +1,316 @@
+"""Unit tests for algovoi_webhook_verifier.verify."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from unittest.mock import patch
+
+import pytest
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+from algovoi_webhook_verifier import WebhookVerificationError, verify_webhook
+
+# --------------------------------------------------------------------------- #
+# Helpers                                                                      #
+# --------------------------------------------------------------------------- #
+
+SECRET = "algvw_test_unit_secret"
+NOW = 1748650000  # fixed timestamp for all tests
+
+
+def _derive_v2_key(secret_bytes: bytes) -> bytes:
+    return HKDF(
+        algorithm=hashes.SHA256(),
+        length=48,
+        salt=b"algovoi-webhook-v2-pqc",
+        info=b"hmac-sha384-outbound",
+    ).derive(secret_bytes)
+
+
+def _sign(secret: str, ts: int, body: bytes) -> str:
+    sb = secret.encode()
+    sp = f"{ts}.".encode() + body
+    v1 = hmac.new(sb, sp, hashlib.sha256).hexdigest()
+    v2_key = _derive_v2_key(sb)
+    v2 = hmac.new(v2_key, sp, hashlib.sha384).hexdigest()
+    return f"t={ts},v1={v1},v2={v2}"
+
+
+def _payment_body(**overrides) -> bytes:
+    data = {
+        "id": "evt_unit_001",
+        "type": "payment.confirmed",
+        "created": NOW,
+        "api_version": "2024-01-01",
+        "data": {},
+    }
+    data.update(overrides)
+    return json.dumps(data, separators=(",", ":")).encode()
+
+
+def _call(body=None, secret=SECRET, ts=NOW, **kw):
+    """Helper: sign body with secret+ts and call verify_webhook with tolerance=0."""
+    if body is None:
+        body = _payment_body()
+    header = _sign(secret, ts, body)
+    return verify_webhook(
+        payload=body,
+        secret=secret,
+        signature_header=header,
+        tolerance=0,
+        **kw,
+    )
+
+
+# --------------------------------------------------------------------------- #
+# Happy-path                                                                   #
+# --------------------------------------------------------------------------- #
+
+class TestHappyPath:
+    def test_returns_parsed_event(self):
+        event = _call()
+        assert event["type"] == "payment.confirmed"
+        assert event["id"] == "evt_unit_001"
+
+    def test_v1_only_accepted_by_default(self):
+        body = _payment_body()
+        sb = SECRET.encode()
+        sp = f"{NOW}.".encode() + body
+        v1 = hmac.new(sb, sp, hashlib.sha256).hexdigest()
+        header = f"t={NOW},v1={v1}"
+        event = verify_webhook(payload=body, secret=SECRET, signature_header=header, tolerance=0)
+        assert event["type"] == "payment.confirmed"
+
+    def test_v2_validated_when_present(self):
+        # Passing require_v2=True with a full sig should succeed
+        event = _call(require_v2=True)
+        assert event["type"] == "payment.confirmed"
+
+    def test_whitespace_trimmed_from_header(self):
+        body = _payment_body()
+        header = "  " + _sign(SECRET, NOW, body) + "  "
+        event = verify_webhook(payload=body, secret=SECRET, signature_header=header, tolerance=0)
+        assert event["type"] == "payment.confirmed"
+
+    def test_custom_tolerance_accepted(self):
+        body = _payment_body()
+        # ts = NOW - 100, fake time = NOW → age = 100 < tolerance 200
+        old_ts = NOW - 100
+        header = _sign(SECRET, old_ts, body)
+        with patch("algovoi_webhook_verifier.verify.time") as mock_time:
+            mock_time.time.return_value = NOW
+            event = verify_webhook(payload=body, secret=SECRET, signature_header=header, tolerance=200)
+        assert event["type"] == "payment.confirmed"
+
+    def test_unicode_body(self):
+        body = json.dumps({
+            "id": "evt_u_001",
+            "type": "payment.confirmed",
+            "created": NOW,
+            "api_version": "2024-01-01",
+            "data": {"label": "café"},
+        }, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+        header = _sign(SECRET, NOW, body)
+        event = verify_webhook(payload=body, secret=SECRET, signature_header=header, tolerance=0)
+        assert event["data"]["label"] == "café"
+
+
+# --------------------------------------------------------------------------- #
+# MISSING_SIGNATURE                                                            #
+# --------------------------------------------------------------------------- #
+
+class TestMissingSignature:
+    @pytest.mark.parametrize("header", ["", None])
+    def test_empty_or_none_header(self, header):
+        body = _payment_body()
+        with pytest.raises(WebhookVerificationError) as exc_info:
+            verify_webhook(payload=body, secret=SECRET, signature_header=header or "", tolerance=0)
+        assert exc_info.value.code == "MISSING_SIGNATURE"
+
+    def test_error_message_contains_header_name(self):
+        with pytest.raises(WebhookVerificationError) as exc_info:
+            verify_webhook(payload=_payment_body(), secret=SECRET, signature_header="", tolerance=0)
+        assert "X-AlgoVoi-Signature" in exc_info.value.message
+
+
+# --------------------------------------------------------------------------- #
+# MALFORMED_SIGNATURE                                                          #
+# --------------------------------------------------------------------------- #
+
+class TestMalformedSignature:
+    @pytest.mark.parametrize("bad_header", [
+        "v1=abc123",
+        "t=abc,v1=abc",                         # non-numeric ts
+        "t=123,v2=abc",                          # missing v1
+        "t=123,v1=" + "a" * 63,                  # v1 too short
+        "t=123,v1=" + "a" * 65,                  # v1 too long
+        "t=123,v1=" + "g" * 64,                  # non-hex v1
+        "randomgarbage",
+    ])
+    def test_rejects_bad_format(self, bad_header):
+        with pytest.raises(WebhookVerificationError) as exc_info:
+            verify_webhook(payload=_payment_body(), secret=SECRET, signature_header=bad_header, tolerance=0)
+        assert exc_info.value.code == "MALFORMED_SIGNATURE"
+
+
+# --------------------------------------------------------------------------- #
+# STALE_SIGNATURE                                                              #
+# --------------------------------------------------------------------------- #
+
+class TestStaleSignature:
+    def test_expired_timestamp(self):
+        body = _payment_body()
+        old_ts = NOW - 600
+        header = _sign(SECRET, old_ts, body)
+        with patch("algovoi_webhook_verifier.verify.time") as mock_time:
+            mock_time.time.return_value = NOW
+            with pytest.raises(WebhookVerificationError) as exc_info:
+                verify_webhook(payload=body, secret=SECRET, signature_header=header, tolerance=300)
+        assert exc_info.value.code == "STALE_SIGNATURE"
+
+    def test_future_timestamp_beyond_tolerance(self):
+        body = _payment_body()
+        future_ts = NOW + 600
+        header = _sign(SECRET, future_ts, body)
+        with patch("algovoi_webhook_verifier.verify.time") as mock_time:
+            mock_time.time.return_value = NOW
+            with pytest.raises(WebhookVerificationError) as exc_info:
+                verify_webhook(payload=body, secret=SECRET, signature_header=header, tolerance=300)
+        assert exc_info.value.code == "STALE_SIGNATURE"
+
+    def test_tolerance_zero_bypasses_check(self):
+        body = _payment_body()
+        old_ts = NOW - 99999
+        header = _sign(SECRET, old_ts, body)
+        # Should NOT raise even though ts is ancient
+        event = verify_webhook(payload=body, secret=SECRET, signature_header=header, tolerance=0)
+        assert event["type"] == "payment.confirmed"
+
+
+# --------------------------------------------------------------------------- #
+# INVALID_SIGNATURE                                                            #
+# --------------------------------------------------------------------------- #
+
+class TestInvalidSignature:
+    def test_wrong_secret(self):
+        body = _payment_body()
+        header = _sign("algvw_wrong_secret", NOW, body)
+        with pytest.raises(WebhookVerificationError) as exc_info:
+            verify_webhook(payload=body, secret=SECRET, signature_header=header, tolerance=0)
+        assert exc_info.value.code == "INVALID_SIGNATURE"
+
+    def test_tampered_body(self):
+        body = _payment_body()
+        header = _sign(SECRET, NOW, body)
+        tampered = body.replace(b"evt_unit_001", b"evt_tampered")
+        with pytest.raises(WebhookVerificationError) as exc_info:
+            verify_webhook(payload=tampered, secret=SECRET, signature_header=header, tolerance=0)
+        assert exc_info.value.code == "INVALID_SIGNATURE"
+
+    def test_corrupted_v1_hex(self):
+        body = _payment_body()
+        header = _sign(SECRET, NOW, body)
+        # Flip last character of v1
+        corrupted = header[:-1] + ("0" if header[-1] != "0" else "1")
+        with pytest.raises(WebhookVerificationError) as exc_info:
+            verify_webhook(payload=body, secret=SECRET, signature_header=corrupted, tolerance=0)
+        assert exc_info.value.code == "INVALID_SIGNATURE"
+
+    def test_require_v2_fails_when_v2_absent(self):
+        body = _payment_body()
+        sb = SECRET.encode()
+        sp = f"{NOW}.".encode() + body
+        v1 = hmac.new(sb, sp, hashlib.sha256).hexdigest()
+        header = f"t={NOW},v1={v1}"  # no v2
+        with pytest.raises(WebhookVerificationError) as exc_info:
+            verify_webhook(payload=body, secret=SECRET, signature_header=header, tolerance=0, require_v2=True)
+        assert exc_info.value.code == "INVALID_SIGNATURE"
+
+    def test_corrupted_v2_hex(self):
+        body = _payment_body()
+        header = _sign(SECRET, NOW, body)
+        # Corrupt the v2 component
+        parts = header.split(",v2=")
+        bad_v2 = parts[1][:-1] + ("0" if parts[1][-1] != "0" else "1")
+        corrupted = parts[0] + ",v2=" + bad_v2
+        with pytest.raises(WebhookVerificationError) as exc_info:
+            verify_webhook(payload=body, secret=SECRET, signature_header=corrupted, tolerance=0)
+        assert exc_info.value.code == "INVALID_SIGNATURE"
+
+
+# --------------------------------------------------------------------------- #
+# INVALID_PAYLOAD                                                              #
+# --------------------------------------------------------------------------- #
+
+class TestInvalidPayload:
+    def test_not_json(self):
+        body = b"not-json"
+        header = _sign(SECRET, NOW, body)
+        with pytest.raises(WebhookVerificationError) as exc_info:
+            verify_webhook(payload=body, secret=SECRET, signature_header=header, tolerance=0)
+        assert exc_info.value.code == "INVALID_PAYLOAD"
+
+    def test_json_array_root(self):
+        body = b'["a","b"]'
+        header = _sign(SECRET, NOW, body)
+        with pytest.raises(WebhookVerificationError) as exc_info:
+            verify_webhook(payload=body, secret=SECRET, signature_header=header, tolerance=0)
+        assert exc_info.value.code == "INVALID_PAYLOAD"
+
+    def test_truncated_json(self):
+        body = b'{"type": "payment.confirmed"'  # missing closing brace
+        header = _sign(SECRET, NOW, body)
+        with pytest.raises(WebhookVerificationError) as exc_info:
+            verify_webhook(payload=body, secret=SECRET, signature_header=header, tolerance=0)
+        assert exc_info.value.code == "INVALID_PAYLOAD"
+
+
+# --------------------------------------------------------------------------- #
+# UNKNOWN_EVENT_TYPE                                                           #
+# --------------------------------------------------------------------------- #
+
+class TestUnknownEventType:
+    @pytest.mark.parametrize("event_type", [
+        "refund.issued",
+        "payment.failed",
+        "mandate.cancelled",
+        None,
+        "",
+    ])
+    def test_unknown_types(self, event_type):
+        data = {
+            "id": "evt_unk",
+            "type": event_type,
+            "created": NOW,
+            "api_version": "2024-01-01",
+            "data": {},
+        }
+        body = json.dumps(data, separators=(",", ":")).encode()
+        header = _sign(SECRET, NOW, body)
+        with pytest.raises(WebhookVerificationError) as exc_info:
+            verify_webhook(payload=body, secret=SECRET, signature_header=header, tolerance=0)
+        assert exc_info.value.code == "UNKNOWN_EVENT_TYPE"
+
+
+# --------------------------------------------------------------------------- #
+# Error object shape                                                           #
+# --------------------------------------------------------------------------- #
+
+class TestErrorObject:
+    def test_error_has_code_and_message(self):
+        with pytest.raises(WebhookVerificationError) as exc_info:
+            verify_webhook(payload=_payment_body(), secret=SECRET, signature_header="", tolerance=0)
+        err = exc_info.value
+        assert isinstance(err.code, str)
+        assert isinstance(err.message, str)
+        assert str(err) == err.message
+
+    def test_repr_contains_code_and_message(self):
+        err = WebhookVerificationError("INVALID_SIGNATURE", "test msg")
+        r = repr(err)
+        assert "INVALID_SIGNATURE" in r
+        assert "test msg" in r