simplex 1.0.8__py3-none-any.whl → 1.0.11__py3-none-any.whl

simplex/__init__.py

@@ -20,8 +20,13 @@ from simplex.errors import (
 )
 from simplex.resources.workflow import Workflow
 from simplex.resources.workflow_session import WorkflowSession
+from simplex.webhook import (
+    verify_simplex_webhook,
+    verify_simplex_webhook_dict,
+    WebhookVerificationError,
+)
 
-__version__ = "1.0.0"
+__version__ = "1.0.11"
 __all__ = [
     "SimplexClient",
     "SimplexError",
@@ -32,4 +37,7 @@ __all__ = [
     "WorkflowError",
     "Workflow",
     "WorkflowSession",
+    "verify_simplex_webhook",
+    "verify_simplex_webhook_dict",
+    "WebhookVerificationError",
 ]

simplex/webhook.py

@@ -0,0 +1,175 @@
+"""
+Webhook verification utilities for Simplex webhooks.
+
+This module provides functions to verify the authenticity of webhook requests
+from Simplex using HMAC-SHA256 signature verification.
+
+Example usage:
+    >>> from simplex import verify_simplex_webhook, WebhookVerificationError
+    >>>
+    >>> try:
+    >>>     verify_simplex_webhook(
+    >>>         body=request.body,
+    >>>         signature=request.headers.get('X-Simplex-Signature'),
+    >>>         webhook_secret='your-webhook-secret'
+    >>>     )
+    >>>     # Webhook verified, safe to process
+    >>> except WebhookVerificationError as e:
+    >>>     # Invalid webhook
+    >>>     print(f"Verification failed: {e}")
+"""
+
+import hmac
+import hashlib
+from typing import Optional, Union, Dict
+
+
+class WebhookVerificationError(Exception):
+    """
+    Exception raised when webhook verification fails.
+
+    This error is raised when:
+    - The signature header is missing
+    - The signature is invalid
+    - The signature doesn't match the expected value
+    """
+
+    def __init__(self, message: str):
+        """
+        Initialize a WebhookVerificationError.
+
+        Args:
+            message: Description of the verification failure
+        """
+        super().__init__(message)
+        self.message = message
+
+
+def verify_simplex_webhook(
+    body: Union[str, bytes],
+    signature: Optional[str],
+    webhook_secret: str
+) -> None:
+    """
+    Verify a Simplex webhook request using HMAC-SHA256 signature verification.
+
+    This function ensures that webhook requests are authentic and haven't been
+    tampered with in transit. It uses the same pattern as GitHub webhooks.
+
+    The signature is computed as: HMAC-SHA256(webhook_secret, request_body)
+
+    Args:
+        body: Raw request body as string or bytes (must be the original unparsed body)
+        signature: The X-Simplex-Signature header value from the request
+        webhook_secret: Your webhook secret from the Simplex dashboard
+
+    Raises:
+        WebhookVerificationError: If signature is missing, invalid, or verification fails
+
+    Example:
+        >>> # Flask example
+        >>> from flask import Flask, request, jsonify
+        >>> from simplex import verify_simplex_webhook, WebhookVerificationError
+        >>>
+        >>> app = Flask(__name__)
+        >>>
+        >>> @app.route('/webhook', methods=['POST'])
+        >>> def webhook():
+        >>>     try:
+        >>>         verify_simplex_webhook(
+        >>>             body=request.get_data(as_text=True),
+        >>>             signature=request.headers.get('X-Simplex-Signature'),
+        >>>             webhook_secret='your-webhook-secret'
+        >>>         )
+        >>>
+        >>>         # Webhook verified, safe to process
+        >>>         payload = request.get_json()
+        >>>         print(f"Received webhook: {payload['session_id']}")
+        >>>         return jsonify({'received': True})
+        >>>
+        >>>     except WebhookVerificationError as e:
+        >>>         return jsonify({'error': str(e)}), 401
+
+    Example:
+        >>> # FastAPI example
+        >>> from fastapi import FastAPI, Request, HTTPException
+        >>> from simplex import verify_simplex_webhook, WebhookVerificationError
+        >>>
+        >>> app = FastAPI()
+        >>>
+        >>> @app.post("/webhook")
+        >>> async def webhook(request: Request):
+        >>>     body = await request.body()
+        >>>     signature = request.headers.get('X-Simplex-Signature')
+        >>>
+        >>>     try:
+        >>>         verify_simplex_webhook(
+        >>>             body=body,
+        >>>             signature=signature,
+        >>>             webhook_secret='your-webhook-secret'
+        >>>         )
+        >>>
+        >>>         payload = await request.json()
+        >>>         return {'received': True}
+        >>>
+        >>>     except WebhookVerificationError as e:
+        >>>         raise HTTPException(status_code=401, detail=str(e))
+    """
+    # 1. Check required signature
+    if not signature:
+        raise WebhookVerificationError('Missing X-Simplex-Signature header')
+
+    # 2. Ensure body is bytes for HMAC computation
+    if isinstance(body, str):
+        body_bytes = body.encode('utf-8')
+    else:
+        body_bytes = body
+
+    # 3. Compute expected signature
+    expected_signature = hmac.new(
+        webhook_secret.encode('utf-8'),
+        body_bytes,
+        hashlib.sha256
+    ).hexdigest()
+
+    # 4. Compare signatures using constant-time comparison to prevent timing attacks
+    if not hmac.compare_digest(expected_signature, signature):
+        raise WebhookVerificationError('Invalid webhook signature')
+
+    # Webhook verified successfully!
+
+
+def verify_simplex_webhook_dict(
+    body: Union[str, bytes],
+    headers: Dict[str, str],
+    webhook_secret: str
+) -> None:
+    """
+    Verify a Simplex webhook request using a headers dictionary.
+
+    This is a convenience wrapper around verify_simplex_webhook() that accepts
+    a headers dictionary and handles case-insensitive header lookup.
+
+    Args:
+        body: Raw request body as string or bytes
+        headers: Dictionary of request headers
+        webhook_secret: Your webhook secret from the Simplex dashboard
+
+    Raises:
+        WebhookVerificationError: If verification fails
+
+    Example:
+        >>> verify_simplex_webhook_dict(
+        >>>     body=request.body,
+        >>>     headers=dict(request.headers),
+        >>>     webhook_secret='your-secret'
+        >>> )
+    """
+    # Try to find the signature header (case-insensitive)
+    signature = None
+    for key, value in headers.items():
+        if key.lower() == 'x-simplex-signature':
+            signature = value
+            break
+
+    verify_simplex_webhook(body, signature, webhook_secret)

{simplex-1.0.8.dist-info → simplex-1.0.11.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simplex
-Version: 1.0.8
+Version: 1.0.11
 Summary: Official Python SDK for the Simplex API
 Home-page: https://github.com/yourusername/simplex-python-sdk
 Author: Simplex

{simplex-1.0.8.dist-info → simplex-1.0.11.dist-info}/RECORD

@@ -1,13 +1,14 @@
-simplex/__init__.py,sha256=brGWID41NoRNE_bquA7G_Neij4zbY826ZdNmOgrnnPY,802
+simplex/__init__.py,sha256=GfMhnfynX-FtWfSo48hJLj3iqgAjCkk49cHqcnuggzw,1023
 simplex/client.py,sha256=SqxjcAZ1dpXUmj-DawGxRdx61Wxrhd-tT1pd84iuEcM,11956
 simplex/errors.py,sha256=_IHJhhvFWWPFywjzXNxbVr2S8WOqThkhc2KzCZiN6i8,4653
 simplex/http_client.py,sha256=-khQqgIenG71oTV73chsbu-uY16NQCgbidiiTVLdIRk,12440
 simplex/types.py,sha256=8pPLJyQPDLuLFuCPRlYJajuJLZbvitE6v27zPkmV6IU,7546
+simplex/webhook.py,sha256=c21YYFk6rStDW2ABHZ__t-a4Lcwn1a1w9WZCkIyRszU,5769
 simplex/resources/__init__.py,sha256=yx_Ubd2LBrXbTwFrhhPgpu3jIy4JqUtb7BJvLnbkGwg,277
 simplex/resources/workflow.py,sha256=FP1c9uTXTgzaggZ485QIhktPKZQW9sOg6d2nbNrywPw,16250
 simplex/resources/workflow_session.py,sha256=3zjwQ55SI1sEP_VncE7w0_jyPrxthMYPJm5O3Uya8p8,10981
-simplex-1.0.8.dist-info/licenses/LICENSE,sha256=TyxVTRp5rBigFCL8EDC9Bv7AZfb4JBMVUZUeCs4Pk6Y,1063
-simplex-1.0.8.dist-info/METADATA,sha256=aB5s0VycncILa2q4shPlJl0FKm-APkjPrQPYjK3NMYY,11161
-simplex-1.0.8.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-simplex-1.0.8.dist-info/top_level.txt,sha256=cbMH1bYpN0A3gP-ecibPRHasHoqB-01T_2BUFS8p0CE,8
-simplex-1.0.8.dist-info/RECORD,,
+simplex-1.0.11.dist-info/licenses/LICENSE,sha256=TyxVTRp5rBigFCL8EDC9Bv7AZfb4JBMVUZUeCs4Pk6Y,1063
+simplex-1.0.11.dist-info/METADATA,sha256=2ucGKD0BvnhiJjBY9vrpB4KOT11QumEZHzFTDrYRJiU,11162
+simplex-1.0.11.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+simplex-1.0.11.dist-info/top_level.txt,sha256=cbMH1bYpN0A3gP-ecibPRHasHoqB-01T_2BUFS8p0CE,8
+simplex-1.0.11.dist-info/RECORD,,