cm-email-webhook-verification 1.0.0__tar.gz

cm_email_webhook_verification-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 CM.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cm_email_webhook_verification-1.0.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: cm-email-webhook-verification
+Version: 1.0.0
+Summary: SDK for verifying CM Email webhook signatures
+Author: email-team
+License: MIT
+Project-URL: Documentation, https://github.com/cmdotcom/email-webhook-verification-sdks#readme
+Project-URL: Repository, https://github.com/cmdotcom/email-webhook-verification-sdks
+Keywords: webhook,verification,hmac,signature,cm,email
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# CM Email Webhook Verification SDK (Python)
+
+SDK for verifying the authenticity of webhooks sent by CM Email services.
+
+## Installation
+
+```bash
+pip install cm-email-webhook-verification
+```
+
+## Usage
+
+```python
+from cm_email_webhook_verification import WebhookValidator, WebhookVerificationError
+
+# Initialize with your webhook secret key
+validator = WebhookValidator("your-secret-key")
+
+# Extract headers and payload from incoming request
+headers = {
+    "svix-id": request.headers["svix-id"],
+    "svix-timestamp": request.headers["svix-timestamp"],
+    "svix-signature": request.headers["svix-signature"],
+}
+payload = request.body.decode("utf-8")
+
+try:
+    data = validator.verify(payload, headers)
+    # Process verified webhook data
+    print(f"Received event: {data}")
+except WebhookVerificationError as e:
+    # Handle verification failure
+    print(f"Webhook verification failed: {e}")
+```
+
+## Flask Example
+
+```python
+from flask import Flask, request, jsonify
+from cm_email_webhook_verification import WebhookValidator, WebhookVerificationError
+
+app = Flask(__name__)
+validator = WebhookValidator("your-secret-key")
+
+@app.route("/webhook", methods=["POST"])
+def webhook():
+    headers = {
+        "svix-id": request.headers.get("svix-id"),
+        "svix-timestamp": request.headers.get("svix-timestamp"),
+        "svix-signature": request.headers.get("svix-signature"),
+    }
+    payload = request.get_data(as_text=True)
+
+    try:
+        data = validator.verify(payload, headers)
+        return jsonify({"status": "ok"}), 200
+    except WebhookVerificationError:
+        return jsonify({"error": "Invalid webhook"}), 401
+```
+
+## FastAPI Example
+
+```python
+from fastapi import FastAPI, Request, HTTPException
+from cm_email_webhook_verification import WebhookValidator, WebhookVerificationError
+
+app = FastAPI()
+validator = WebhookValidator("your-secret-key")
+
+@app.post("/webhook")
+async def webhook(request: Request):
+    headers = {
+        "svix-id": request.headers.get("svix-id"),
+        "svix-timestamp": request.headers.get("svix-timestamp"),
+        "svix-signature": request.headers.get("svix-signature"),
+    }
+    payload = (await request.body()).decode("utf-8")
+
+    try:
+        data = validator.verify(payload, headers)
+        return {"status": "ok"}
+    except WebhookVerificationError:
+        raise HTTPException(status_code=401, detail="Invalid webhook")
+```
+
+## Custom Tolerance
+
+By default, webhooks are valid for 5 minutes. You can customize this:
+
+```python
+# Accept webhooks up to 10 minutes old
+validator = WebhookValidator("your-secret-key", tolerance_in_seconds=600)
+```
+
+## Exceptions
+
+| Exception | Description |
+|-----------|-------------|
+| `WebhookVerificationError` | Base exception for all verification errors |
+| `InvalidSignatureError` | Signature does not match |
+| `TimestampExpiredError` | Timestamp outside tolerance window |
+| `MissingHeaderError` | Required headers missing |
+
+## Security
+
+This SDK uses:
+- **HMAC-SHA512** for signature generation
+- **Constant-time comparison** to prevent timing attacks
+- **Timestamp validation** to prevent replay attacks
+

cm_email_webhook_verification-1.0.0/README.md

@@ -0,0 +1,110 @@
+# CM Email Webhook Verification SDK (Python)
+
+SDK for verifying the authenticity of webhooks sent by CM Email services.
+
+## Installation
+
+```bash
+pip install cm-email-webhook-verification
+```
+
+## Usage
+
+```python
+from cm_email_webhook_verification import WebhookValidator, WebhookVerificationError
+
+# Initialize with your webhook secret key
+validator = WebhookValidator("your-secret-key")
+
+# Extract headers and payload from incoming request
+headers = {
+    "svix-id": request.headers["svix-id"],
+    "svix-timestamp": request.headers["svix-timestamp"],
+    "svix-signature": request.headers["svix-signature"],
+}
+payload = request.body.decode("utf-8")
+
+try:
+    data = validator.verify(payload, headers)
+    # Process verified webhook data
+    print(f"Received event: {data}")
+except WebhookVerificationError as e:
+    # Handle verification failure
+    print(f"Webhook verification failed: {e}")
+```
+
+## Flask Example
+
+```python
+from flask import Flask, request, jsonify
+from cm_email_webhook_verification import WebhookValidator, WebhookVerificationError
+
+app = Flask(__name__)
+validator = WebhookValidator("your-secret-key")
+
+@app.route("/webhook", methods=["POST"])
+def webhook():
+    headers = {
+        "svix-id": request.headers.get("svix-id"),
+        "svix-timestamp": request.headers.get("svix-timestamp"),
+        "svix-signature": request.headers.get("svix-signature"),
+    }
+    payload = request.get_data(as_text=True)
+
+    try:
+        data = validator.verify(payload, headers)
+        return jsonify({"status": "ok"}), 200
+    except WebhookVerificationError:
+        return jsonify({"error": "Invalid webhook"}), 401
+```
+
+## FastAPI Example
+
+```python
+from fastapi import FastAPI, Request, HTTPException
+from cm_email_webhook_verification import WebhookValidator, WebhookVerificationError
+
+app = FastAPI()
+validator = WebhookValidator("your-secret-key")
+
+@app.post("/webhook")
+async def webhook(request: Request):
+    headers = {
+        "svix-id": request.headers.get("svix-id"),
+        "svix-timestamp": request.headers.get("svix-timestamp"),
+        "svix-signature": request.headers.get("svix-signature"),
+    }
+    payload = (await request.body()).decode("utf-8")
+
+    try:
+        data = validator.verify(payload, headers)
+        return {"status": "ok"}
+    except WebhookVerificationError:
+        raise HTTPException(status_code=401, detail="Invalid webhook")
+```
+
+## Custom Tolerance
+
+By default, webhooks are valid for 5 minutes. You can customize this:
+
+```python
+# Accept webhooks up to 10 minutes old
+validator = WebhookValidator("your-secret-key", tolerance_in_seconds=600)
+```
+
+## Exceptions
+
+| Exception | Description |
+|-----------|-------------|
+| `WebhookVerificationError` | Base exception for all verification errors |
+| `InvalidSignatureError` | Signature does not match |
+| `TimestampExpiredError` | Timestamp outside tolerance window |
+| `MissingHeaderError` | Required headers missing |
+
+## Security
+
+This SDK uses:
+- **HMAC-SHA512** for signature generation
+- **Constant-time comparison** to prevent timing attacks
+- **Timestamp validation** to prevent replay attacks
+

cm_email_webhook_verification-1.0.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cm-email-webhook-verification"
+version = "1.0.0"
+description = "SDK for verifying CM Email webhook signatures"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [ {name = "email-team"} ]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT 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",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security :: Cryptography",
+    "Typing :: Typed",
+]
+
+keywords = ["webhook", "verification", "hmac", "signature", "cm", "email"]
+dependencies = []
+
+[project.urls]
+Documentation = "https://github.com/cmdotcom/email-webhook-verification-sdks#readme"
+Repository = "https://github.com/cmdotcom/email-webhook-verification-sdks"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "mypy>=1.0",
+    "ruff>=0.1.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+strict = true
+
+[tool.ruff]
+target-version = "py39"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "C4", "SIM"]

cm_email_webhook_verification-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cm_email_webhook_verification-1.0.0/src/cm_email_webhook_verification/__init__.py

@@ -0,0 +1,23 @@
+from typing import Any
+
+from cm_email_webhook_verification.exceptions import (
+    InvalidSignatureError,
+    MissingHeaderError,
+    TimestampExpiredError,
+    WebhookVerificationError,
+)
+from cm_email_webhook_verification.validator import WebhookValidator
+
+__version__ = "1.0.0"
+__all__ = [
+    "verify",
+    "WebhookValidator",
+    "WebhookVerificationError",
+    "InvalidSignatureError",
+    "TimestampExpiredError",
+    "MissingHeaderError",
+]
+
+
+def verify(secret_key: str, payload: str, headers: dict[str, str]) -> Any:
+    return WebhookValidator(secret_key).verify(payload, headers)

cm_email_webhook_verification-1.0.0/src/cm_email_webhook_verification/exceptions.py

@@ -0,0 +1,14 @@
+class WebhookVerificationError(Exception):
+    pass
+
+
+class InvalidSignatureError(WebhookVerificationError):
+    pass
+
+
+class TimestampExpiredError(WebhookVerificationError):
+    pass
+
+
+class MissingHeaderError(WebhookVerificationError):
+    pass

cm_email_webhook_verification-1.0.0/src/cm_email_webhook_verification/signer.py

@@ -0,0 +1,11 @@
+import base64
+import hashlib
+import hmac
+
+
+def generate_signature(secret: str, payload: str) -> str:
+    key_bytes = secret.encode("utf-8")
+    payload_bytes = payload.encode("utf-8")
+
+    signature = hmac.new(key_bytes, payload_bytes, hashlib.sha512)
+    return base64.b64encode(signature.digest()).decode("utf-8")

cm_email_webhook_verification-1.0.0/src/cm_email_webhook_verification/validator.py

@@ -0,0 +1,69 @@
+import hmac
+import json
+import time
+from typing import Any
+
+from cm_email_webhook_verification.exceptions import (
+    InvalidSignatureError,
+    MissingHeaderError,
+    TimestampExpiredError,
+)
+from cm_email_webhook_verification.signer import generate_signature
+
+
+class WebhookValidator:
+    HEADER_ID = "svix-id"
+    HEADER_TIMESTAMP = "svix-timestamp"
+    HEADER_SIGNATURE = "svix-signature"
+
+    def __init__(self, secret_key: str, tolerance_in_seconds: int = 300) -> None:
+        if not secret_key or not secret_key.strip():
+            raise ValueError("secret_key cannot be empty")
+
+        self._secret_key = secret_key
+        self._tolerance_ms = tolerance_in_seconds * 1000
+
+    def verify(self, payload: str, headers: dict[str, str]) -> Any:
+        if not payload or not payload.strip():
+            raise ValueError("payload cannot be empty")
+
+        if headers is None:
+            raise ValueError("headers cannot be None")
+
+        message_id = headers.get(self.HEADER_ID)
+        timestamp_str = headers.get(self.HEADER_TIMESTAMP)
+        signature = headers.get(self.HEADER_SIGNATURE)
+
+        if not message_id or not timestamp_str or not signature:
+            missing = []
+            if not message_id:
+                missing.append(self.HEADER_ID)
+            if not timestamp_str:
+                missing.append(self.HEADER_TIMESTAMP)
+            if not signature:
+                missing.append(self.HEADER_SIGNATURE)
+            raise MissingHeaderError(f"Missing required headers: {', '.join(missing)}")
+
+        try:
+            timestamp_ms = int(timestamp_str)
+        except ValueError as e:
+            raise ValueError("Invalid timestamp format") from e
+
+        self._validate_timestamp(timestamp_ms)
+
+        signature_payload = f"{message_id}.{timestamp_ms}.{payload}"
+        expected_signature = generate_signature(self._secret_key, signature_payload)
+
+        if not hmac.compare_digest(signature, expected_signature):
+            raise InvalidSignatureError("Invalid signature")
+
+        return json.loads(payload)
+
+    def _validate_timestamp(self, timestamp_ms: int) -> None:
+        current_time_ms = int(time.time() * 1000)
+        difference = abs(current_time_ms - timestamp_ms)
+
+        if difference > self._tolerance_ms:
+            raise TimestampExpiredError(
+                "Webhook timestamp is outside the allowed tolerance window"
+            )

cm_email_webhook_verification-1.0.0/src/cm_email_webhook_verification.egg-info/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: cm-email-webhook-verification
+Version: 1.0.0
+Summary: SDK for verifying CM Email webhook signatures
+Author: email-team
+License: MIT
+Project-URL: Documentation, https://github.com/cmdotcom/email-webhook-verification-sdks#readme
+Project-URL: Repository, https://github.com/cmdotcom/email-webhook-verification-sdks
+Keywords: webhook,verification,hmac,signature,cm,email
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# CM Email Webhook Verification SDK (Python)
+
+SDK for verifying the authenticity of webhooks sent by CM Email services.
+
+## Installation
+
+```bash
+pip install cm-email-webhook-verification
+```
+
+## Usage
+
+```python
+from cm_email_webhook_verification import WebhookValidator, WebhookVerificationError
+
+# Initialize with your webhook secret key
+validator = WebhookValidator("your-secret-key")
+
+# Extract headers and payload from incoming request
+headers = {
+    "svix-id": request.headers["svix-id"],
+    "svix-timestamp": request.headers["svix-timestamp"],
+    "svix-signature": request.headers["svix-signature"],
+}
+payload = request.body.decode("utf-8")
+
+try:
+    data = validator.verify(payload, headers)
+    # Process verified webhook data
+    print(f"Received event: {data}")
+except WebhookVerificationError as e:
+    # Handle verification failure
+    print(f"Webhook verification failed: {e}")
+```
+
+## Flask Example
+
+```python
+from flask import Flask, request, jsonify
+from cm_email_webhook_verification import WebhookValidator, WebhookVerificationError
+
+app = Flask(__name__)
+validator = WebhookValidator("your-secret-key")
+
+@app.route("/webhook", methods=["POST"])
+def webhook():
+    headers = {
+        "svix-id": request.headers.get("svix-id"),
+        "svix-timestamp": request.headers.get("svix-timestamp"),
+        "svix-signature": request.headers.get("svix-signature"),
+    }
+    payload = request.get_data(as_text=True)
+
+    try:
+        data = validator.verify(payload, headers)
+        return jsonify({"status": "ok"}), 200
+    except WebhookVerificationError:
+        return jsonify({"error": "Invalid webhook"}), 401
+```
+
+## FastAPI Example
+
+```python
+from fastapi import FastAPI, Request, HTTPException
+from cm_email_webhook_verification import WebhookValidator, WebhookVerificationError
+
+app = FastAPI()
+validator = WebhookValidator("your-secret-key")
+
+@app.post("/webhook")
+async def webhook(request: Request):
+    headers = {
+        "svix-id": request.headers.get("svix-id"),
+        "svix-timestamp": request.headers.get("svix-timestamp"),
+        "svix-signature": request.headers.get("svix-signature"),
+    }
+    payload = (await request.body()).decode("utf-8")
+
+    try:
+        data = validator.verify(payload, headers)
+        return {"status": "ok"}
+    except WebhookVerificationError:
+        raise HTTPException(status_code=401, detail="Invalid webhook")
+```
+
+## Custom Tolerance
+
+By default, webhooks are valid for 5 minutes. You can customize this:
+
+```python
+# Accept webhooks up to 10 minutes old
+validator = WebhookValidator("your-secret-key", tolerance_in_seconds=600)
+```
+
+## Exceptions
+
+| Exception | Description |
+|-----------|-------------|
+| `WebhookVerificationError` | Base exception for all verification errors |
+| `InvalidSignatureError` | Signature does not match |
+| `TimestampExpiredError` | Timestamp outside tolerance window |
+| `MissingHeaderError` | Required headers missing |
+
+## Security
+
+This SDK uses:
+- **HMAC-SHA512** for signature generation
+- **Constant-time comparison** to prevent timing attacks
+- **Timestamp validation** to prevent replay attacks
+

cm_email_webhook_verification-1.0.0/src/cm_email_webhook_verification.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/cm_email_webhook_verification/__init__.py
+src/cm_email_webhook_verification/exceptions.py
+src/cm_email_webhook_verification/signer.py
+src/cm_email_webhook_verification/validator.py
+src/cm_email_webhook_verification.egg-info/PKG-INFO
+src/cm_email_webhook_verification.egg-info/SOURCES.txt
+src/cm_email_webhook_verification.egg-info/dependency_links.txt
+src/cm_email_webhook_verification.egg-info/requires.txt
+src/cm_email_webhook_verification.egg-info/top_level.txt
+tests/test_validator.py

cm_email_webhook_verification-1.0.0/src/cm_email_webhook_verification.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cm_email_webhook_verification-1.0.0/src/cm_email_webhook_verification.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[dev]
+pytest>=7.0
+pytest-cov>=4.0
+mypy>=1.0
+ruff>=0.1.0

cm_email_webhook_verification-1.0.0/src/cm_email_webhook_verification.egg-info/top_level.txt

@@ -0,0 +1 @@
+cm_email_webhook_verification

cm_email_webhook_verification-1.0.0/tests/test_validator.py

@@ -0,0 +1,177 @@
+import json
+import time
+
+import pytest
+
+from cm_email_webhook_verification import (
+    InvalidSignatureError,
+    MissingHeaderError,
+    TimestampExpiredError,
+    WebhookValidator,
+)
+from cm_email_webhook_verification.signer import generate_signature
+
+
+class TestWebhookValidator:
+
+    def setup_method(self) -> None:
+        self.secret_key = "test-secret-key"
+        self.validator = WebhookValidator(self.secret_key)
+
+    def _create_valid_headers(self, payload: str) -> dict[str, str]:
+        message_id = "msg-123"
+        timestamp_ms = int(time.time() * 1000)
+        signature_payload = f"{message_id}.{timestamp_ms}.{payload}"
+        signature = generate_signature(self.secret_key, signature_payload)
+
+        return {
+            "svix-id": message_id,
+            "svix-timestamp": str(timestamp_ms),
+            "svix-signature": signature,
+        }
+
+    def test_verify_valid_webhook(self) -> None:
+        payload = json.dumps({"event": "test", "data": {"id": 123}})
+        headers = self._create_valid_headers(payload)
+
+        result = self.validator.verify(payload, headers)
+
+        assert result["event"] == "test"
+        assert result["data"]["id"] == 123
+
+    def test_verify_invalid_signature(self) -> None:
+        payload = json.dumps({"event": "test"})
+        headers = self._create_valid_headers(payload)
+        headers["svix-signature"] = "invalid-signature"
+
+        with pytest.raises(InvalidSignatureError):
+            self.validator.verify(payload, headers)
+
+    def test_verify_missing_headers(self) -> None:
+        payload = json.dumps({"event": "test"})
+
+        with pytest.raises(MissingHeaderError):
+            self.validator.verify(payload, {})
+
+    def test_verify_missing_single_header(self) -> None:
+        payload = json.dumps({"event": "test"})
+        headers = self._create_valid_headers(payload)
+        del headers["svix-id"]
+
+        with pytest.raises(MissingHeaderError) as exc_info:
+            self.validator.verify(payload, headers)
+
+        assert "svix-id" in str(exc_info.value)
+
+    def test_verify_expired_timestamp(self) -> None:
+        payload = json.dumps({"event": "test"})
+        message_id = "msg-123"
+        # Timestamp from 10 minutes ago
+        timestamp_ms = int((time.time() - 600) * 1000)
+        signature_payload = f"{message_id}.{timestamp_ms}.{payload}"
+        signature = generate_signature(self.secret_key, signature_payload)
+
+        headers = {
+            "svix-id": message_id,
+            "svix-timestamp": str(timestamp_ms),
+            "svix-signature": signature,
+        }
+
+        with pytest.raises(TimestampExpiredError):
+            self.validator.verify(payload, headers)
+
+    def test_verify_future_timestamp_within_tolerance(self) -> None:
+        payload = json.dumps({"event": "test"})
+        message_id = "msg-123"
+        # Timestamp 1 minute in the future
+        timestamp_ms = int((time.time() + 60) * 1000)
+        signature_payload = f"{message_id}.{timestamp_ms}.{payload}"
+        signature = generate_signature(self.secret_key, signature_payload)
+
+        headers = {
+            "svix-id": message_id,
+            "svix-timestamp": str(timestamp_ms),
+            "svix-signature": signature,
+        }
+
+        result = self.validator.verify(payload, headers)
+        assert result["event"] == "test"
+
+    def test_verify_empty_payload(self) -> None:
+        headers = {"svix-id": "123", "svix-timestamp": "123", "svix-signature": "sig"}
+
+        with pytest.raises(ValueError):
+            self.validator.verify("", headers)
+
+    def test_verify_none_headers(self) -> None:
+        with pytest.raises(ValueError):
+            self.validator.verify('{"event": "test"}', None)  # type: ignore
+
+    def test_constructor_empty_secret(self) -> None:
+        with pytest.raises(ValueError):
+            WebhookValidator("")
+
+    def test_constructor_whitespace_secret(self) -> None:
+        with pytest.raises(ValueError):
+            WebhookValidator("   ")
+
+    def test_custom_tolerance(self) -> None:
+        # Create validator with 1 second tolerance
+        validator = WebhookValidator(self.secret_key, tolerance_in_seconds=1)
+
+        payload = json.dumps({"event": "test"})
+        message_id = "msg-123"
+        # Timestamp from 5 seconds ago
+        timestamp_ms = int((time.time() - 5) * 1000)
+        signature_payload = f"{message_id}.{timestamp_ms}.{payload}"
+        signature = generate_signature(self.secret_key, signature_payload)
+
+        headers = {
+            "svix-id": message_id,
+            "svix-timestamp": str(timestamp_ms),
+            "svix-signature": signature,
+        }
+
+        with pytest.raises(TimestampExpiredError):
+            validator.verify(payload, headers)
+
+    def test_invalid_timestamp_format(self) -> None:
+        payload = json.dumps({"event": "test"})
+        headers = {
+            "svix-id": "msg-123",
+            "svix-timestamp": "not-a-number",
+            "svix-signature": "signature",
+        }
+
+        with pytest.raises(ValueError) as exc_info:
+            self.validator.verify(payload, headers)
+
+        assert "timestamp" in str(exc_info.value).lower()
+
+
+class TestGenerateSignature:
+
+    def test_generate_signature_deterministic(self) -> None:
+        secret = "test-secret"
+        payload = "test-payload"
+
+        sig1 = generate_signature(secret, payload)
+        sig2 = generate_signature(secret, payload)
+
+        assert sig1 == sig2
+
+    def test_generate_signature_different_secrets(self) -> None:
+        payload = "test-payload"
+
+        sig1 = generate_signature("secret1", payload)
+        sig2 = generate_signature("secret2", payload)
+
+        assert sig1 != sig2
+
+    def test_generate_signature_different_payloads(self) -> None:
+        secret = "test-secret"
+
+        sig1 = generate_signature(secret, "payload1")
+        sig2 = generate_signature(secret, "payload2")
+
+        assert sig1 != sig2