Stripe Webhook Signature Verification Handler – Timestamp Header

Task: Create a complete, production‑ready Stripe webhook signature verification handler in Python 3.11 (or a language of your choice, but default to Python). The handler must securely verify incoming Stripe webhook requests, parse the event payload, and provide clear error handling. Include comprehensive inline documentation, type hints, and a usage example. Additionally, supply a full suite of unit tests (using pytest) that cover all success and failure scenarios, and a short README snippet showing how to integrate the handler into a typical web framework (e.g., Flask or FastAPI).

Requirements:

1. Core Functionality

   • Implement a function verify_stripe_signature(payload: bytes, sig_header: str, secret: str, tolerance: int = 300) -> dict that:
     • Parses the Stripe-Signature header to extract the timestamp (t) and one or more signatures (v1).
     • Validates that the timestamp is within tolerance seconds of the current UTC time.
     • Computes the HMAC‑SHA256 signature of the string "t.{payload}" using the provided secret.
     • Performs a constant‑time comparison between the computed signature and each v1 signature from the header.
     • Returns the decoded JSON payload as a Python dictionary if verification succeeds.
     • Raises a custom exception StripeSignatureVerificationError with an informative message for any failure (missing header, malformed header, timestamp out of range, signature mismatch, JSON decode error, etc.).

2. Helper Types & Exceptions

   • Define a @dataclass named StripeSignatureComponents with fields timestamp: int and signatures: List[str].
   • Define the custom exception class StripeSignatureVerificationError(RuntimeError).

3. Usage Example

   • Provide a short, runnable example showing how to use the function inside a Flask route (/webhook) and a FastAPI endpoint. Include how to retrieve the raw request body and the Stripe-Signature header.

4. Unit Tests (pytest)

   • Create a file test_stripe_signature.py containing at least the following tests:
     • Successful verification with a valid signature.
     • Failure when the Stripe-Signature header is missing.
     • Failure when the header cannot be parsed.
     • Failure when the timestamp is older than tolerance.
     • Failure when the computed signature does not match any v1 signature.
     • Failure when the payload is not valid JSON.
   • Use fixtures to generate a deterministic secret and payload, and to compute a correct signature for the success case.
   • Ensure tests run in isolation and do not require external network calls.

5. README Snippet

   • Provide a concise markdown section (≤ 150 words) titled “Integrating the Stripe Signature Verifier” that explains:
     • Installing required dependencies (pip install stripe cryptography pytest etc.).
     • Importing the verifier.
     • Adding the verification step to a webhook endpoint.
     • Handling StripeSignatureVerificationError.

6. Code Quality

   • Use type hints throughout.
   • Follow PEP 8 style guidelines.
   • Include docstrings for all public objects.
   • Use hmac.compare_digest for constant‑time comparison.
   • Do not hard‑code any secret; accept it as a parameter.

Expected Output Format:

• File 1: stripe_signature_verifier.py – contains the implementation, helper dataclass, exception, and usage examples (as a if __name__ == "__main__": block or separate functions).
• File 2: test_stripe_signature.py – full pytest suite as described.
• File 3: README.md – the integration snippet.

Present each file as a separate fenced code block with the appropriate language tag (python for the first two, markdown for the README). Ensure the code blocks are ready to be copied verbatim into a project.