relaya 0.1.0__tar.gz

relaya-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dhiraj Kumar
+
+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.

relaya-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: relaya
+Version: 0.1.0
+Summary: Verify webhooks forwarded by Relaya and call the Relaya API.
+License: MIT
+Project-URL: Homepage, https://github.com/Dhirajrai12/relaya-sdks/tree/main/python
+Project-URL: Source, https://github.com/Dhirajrai12/relaya-sdks
+Keywords: relaya,webhooks,signature,hmac,integrations
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# relaya (Python)
+
+Verify requests that Relaya forwards to your endpoints, and call the Relaya API. No dependencies; Python 3.9+.
+
+```sh
+pip install relaya
+```
+
+## Receive events
+
+Relaya signs every request it forwards with your destination's signing secret (shown once when you add the destination). Always pass the **raw** body.
+
+### Django
+
+```python
+from django.http import HttpResponse, JsonResponse
+from django.views.decorators.csrf import csrf_exempt
+from django.views.decorators.http import require_POST
+from relaya import verify_delivery, WebhookVerificationError
+
+@csrf_exempt
+@require_POST
+def relaya_webhook(request):
+    try:
+        delivery = verify_delivery(request.body, request.headers, settings.RELAYA_SIGNING_SECRET)
+    except WebhookVerificationError as e:
+        return JsonResponse({"error": e.reason}, status=400)
+    if already_processed(delivery.idempotency_key):
+        return HttpResponse()
+    handle(delivery.json())
+    return HttpResponse()
+```
+
+### Flask
+
+```python
+@app.post("/webhooks/relaya")
+def relaya_webhook():
+    try:
+        delivery = verify_delivery(request.get_data(), request.headers, os.environ["RELAYA_SIGNING_SECRET"])
+    except WebhookVerificationError as e:
+        return {"error": e.reason}, 400
+    handle(delivery.json())
+    return "", 200
+```
+
+### FastAPI
+
+```python
+@app.post("/webhooks/relaya")
+async def relaya_webhook(request: Request):
+    try:
+        delivery = verify_delivery(await request.body(), request.headers, os.environ["RELAYA_SIGNING_SECRET"])
+    except WebhookVerificationError as e:
+        raise HTTPException(400, e.reason)
+    await handle(delivery.json())
+```
+
+Return a 5xx and Relaya retries later with the same idempotency key.
+
+| `Delivery` field | |
+|---|---|
+| `idempotency_key` | The same across retries and replays of one delivery. Dedupe on this. |
+| `event_id`, `delivery_id` | Relaya's IDs. |
+| `event_type` | e.g. `payment.captured`, when Relaya could tell. |
+| `attempt` | 1, then 2, 3… on retries. |
+| `replay_id` | Set when the request is part of an incident replay. |
+| `body`, `json()` | The provider's original body, unchanged. |
+
+`e.reason` is one of `missing_signature`, `malformed_signature`, `timestamp_out_of_range`, `signature_mismatch`. Pass a list of secrets while rotating; `tolerance=` sets the maximum signature age in seconds (default 300, `0` disables). Webhook alert channels: `verify_alert(body, headers, secret)`.
+
+## Call the API
+
+```python
+from datetime import datetime, timedelta, timezone
+from relaya import Relaya
+
+relaya = Relaya()  # reads RELAYA_API_KEY
+
+for event in relaya.events.iterate(contract_status="breaking", since=datetime.now(timezone.utc) - timedelta(days=7)):
+    print(event["type"], event["received_at"])
+
+for d in relaya.deliveries.list(status="failed"):
+    relaya.deliveries.retry(d["id"])
+
+for incident in relaya.incidents.list("open"):
+    plan = relaya.incidents.preview_replay(incident["id"])  # dry run
+    relaya.incidents.replay(incident["id"])                 # resolves itself once every delivery succeeds
+```
+
+Resources: `projects`, `webhooks`, `events` (`list`, `iterate`, `get`), `destinations`, `deliveries`, `contracts`, `incidents`, `alerts`. Responses are dicts with the API's field names. `relaya.request(method, path, body, params)` reaches anything else.
+
+Options: `api_key` (or `RELAYA_API_KEY`), `base_url` (or `RELAYA_BASE_URL`), `org_id` (only with a session token), `timeout` (30 s), `max_retries` (2; GET only, on network errors, 429 and 5xx).
+
+Errors raise `RelayaError` with `status`, `code` and `request_id`.
+
+## Development
+
+```sh
+PYTHONPATH=src python -m unittest discover -s tests
+RELAYA_IT_API_URL=http://127.0.0.1:18080 PYTHONPATH=src python -m unittest tests.test_integration   # against a running dev stack
+```

relaya-0.1.0/README.md

@@ -0,0 +1,102 @@
+# relaya (Python)
+
+Verify requests that Relaya forwards to your endpoints, and call the Relaya API. No dependencies; Python 3.9+.
+
+```sh
+pip install relaya
+```
+
+## Receive events
+
+Relaya signs every request it forwards with your destination's signing secret (shown once when you add the destination). Always pass the **raw** body.
+
+### Django
+
+```python
+from django.http import HttpResponse, JsonResponse
+from django.views.decorators.csrf import csrf_exempt
+from django.views.decorators.http import require_POST
+from relaya import verify_delivery, WebhookVerificationError
+
+@csrf_exempt
+@require_POST
+def relaya_webhook(request):
+    try:
+        delivery = verify_delivery(request.body, request.headers, settings.RELAYA_SIGNING_SECRET)
+    except WebhookVerificationError as e:
+        return JsonResponse({"error": e.reason}, status=400)
+    if already_processed(delivery.idempotency_key):
+        return HttpResponse()
+    handle(delivery.json())
+    return HttpResponse()
+```
+
+### Flask
+
+```python
+@app.post("/webhooks/relaya")
+def relaya_webhook():
+    try:
+        delivery = verify_delivery(request.get_data(), request.headers, os.environ["RELAYA_SIGNING_SECRET"])
+    except WebhookVerificationError as e:
+        return {"error": e.reason}, 400
+    handle(delivery.json())
+    return "", 200
+```
+
+### FastAPI
+
+```python
+@app.post("/webhooks/relaya")
+async def relaya_webhook(request: Request):
+    try:
+        delivery = verify_delivery(await request.body(), request.headers, os.environ["RELAYA_SIGNING_SECRET"])
+    except WebhookVerificationError as e:
+        raise HTTPException(400, e.reason)
+    await handle(delivery.json())
+```
+
+Return a 5xx and Relaya retries later with the same idempotency key.
+
+| `Delivery` field | |
+|---|---|
+| `idempotency_key` | The same across retries and replays of one delivery. Dedupe on this. |
+| `event_id`, `delivery_id` | Relaya's IDs. |
+| `event_type` | e.g. `payment.captured`, when Relaya could tell. |
+| `attempt` | 1, then 2, 3… on retries. |
+| `replay_id` | Set when the request is part of an incident replay. |
+| `body`, `json()` | The provider's original body, unchanged. |
+
+`e.reason` is one of `missing_signature`, `malformed_signature`, `timestamp_out_of_range`, `signature_mismatch`. Pass a list of secrets while rotating; `tolerance=` sets the maximum signature age in seconds (default 300, `0` disables). Webhook alert channels: `verify_alert(body, headers, secret)`.
+
+## Call the API
+
+```python
+from datetime import datetime, timedelta, timezone
+from relaya import Relaya
+
+relaya = Relaya()  # reads RELAYA_API_KEY
+
+for event in relaya.events.iterate(contract_status="breaking", since=datetime.now(timezone.utc) - timedelta(days=7)):
+    print(event["type"], event["received_at"])
+
+for d in relaya.deliveries.list(status="failed"):
+    relaya.deliveries.retry(d["id"])
+
+for incident in relaya.incidents.list("open"):
+    plan = relaya.incidents.preview_replay(incident["id"])  # dry run
+    relaya.incidents.replay(incident["id"])                 # resolves itself once every delivery succeeds
+```
+
+Resources: `projects`, `webhooks`, `events` (`list`, `iterate`, `get`), `destinations`, `deliveries`, `contracts`, `incidents`, `alerts`. Responses are dicts with the API's field names. `relaya.request(method, path, body, params)` reaches anything else.
+
+Options: `api_key` (or `RELAYA_API_KEY`), `base_url` (or `RELAYA_BASE_URL`), `org_id` (only with a session token), `timeout` (30 s), `max_retries` (2; GET only, on network errors, 429 and 5xx).
+
+Errors raise `RelayaError` with `status`, `code` and `request_id`.
+
+## Development
+
+```sh
+PYTHONPATH=src python -m unittest discover -s tests
+RELAYA_IT_API_URL=http://127.0.0.1:18080 PYTHONPATH=src python -m unittest tests.test_integration   # against a running dev stack
+```

relaya-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "relaya"
+version = "0.1.0"
+description = "Verify webhooks forwarded by Relaya and call the Relaya API."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+dependencies = []
+keywords = ["relaya", "webhooks", "signature", "hmac", "integrations"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/Dhirajrai12/relaya-sdks/tree/main/python"
+Source = "https://github.com/Dhirajrai12/relaya-sdks"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+relaya = ["py.typed"]

relaya-0.1.0/setup.cfg

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

relaya-0.1.0/src/relaya/__init__.py

@@ -0,0 +1,28 @@
+"""Verify webhooks forwarded by Relaya and call the Relaya API."""
+
+__version__ = "0.1.0"
+
+from .client import DEFAULT_BASE_URL, Relaya  # noqa: E402
+from .errors import RelayaError, WebhookVerificationError  # noqa: E402
+from .webhooks import (  # noqa: E402
+    DEFAULT_TOLERANCE,
+    Delivery,
+    is_valid_signature,
+    verify_alert,
+    verify_delivery,
+    verify_signature,
+)
+
+__all__ = [
+    "Relaya",
+    "RelayaError",
+    "WebhookVerificationError",
+    "Delivery",
+    "verify_signature",
+    "is_valid_signature",
+    "verify_delivery",
+    "verify_alert",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TOLERANCE",
+    "__version__",
+]

relaya-0.1.0/src/relaya/client.py

@@ -0,0 +1,289 @@
+"""Relaya API client. Responses are plain dicts with the API's field names."""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+import socket
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from datetime import datetime, timezone
+from typing import Any, Dict, Iterator, List, Optional
+
+from . import __version__
+from .errors import RelayaError
+
+#: Where the API lives until the product has its own domain.
+DEFAULT_BASE_URL = "https://server.aegonassett.com/api"
+
+JSON = Dict[str, Any]
+
+
+def _clean(params: Dict[str, Any]) -> Dict[str, str]:
+    out = {}
+    for k, v in params.items():
+        if v is None or v == "":
+            continue
+        if isinstance(v, datetime):
+            v = (v if v.tzinfo else v.replace(tzinfo=timezone.utc)).astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+        out[k] = str(v)
+    return out
+
+
+def _backoff(attempt: int, retry_after: Optional[str]) -> float:
+    if retry_after is not None:
+        try:
+            return min(max(float(retry_after), 0.0), 30.0)
+        except ValueError:
+            pass
+    return min(0.5 * 2**attempt, 8.0) * (0.8 + random.random() * 0.4)
+
+
+class Relaya:
+    """Relaya API client.
+
+    >>> relaya = Relaya(api_key=os.environ["RELAYA_API_KEY"])
+    >>> for event in relaya.events.iterate(contract_status="breaking"):
+    ...     print(event["type"])
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        org_id: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("RELAYA_API_KEY")
+        if not self.api_key:
+            raise ValueError("relaya: pass api_key or set RELAYA_API_KEY")
+        self.base_url = (base_url or os.environ.get("RELAYA_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._org_id = org_id
+        self._org_lock = threading.Lock()
+
+        self.projects = Projects(self)
+        self.webhooks = Webhooks(self)
+        self.events = Events(self)
+        self.destinations = Destinations(self)
+        self.deliveries = Deliveries(self)
+        self.contracts = Contracts(self)
+        self.incidents = Incidents(self)
+        self.alerts = Alerts(self)
+
+    @property
+    def org_id(self) -> str:
+        """The org this client acts on, looked up from the API key on first use."""
+        with self._org_lock:
+            if not self._org_id:
+                me = self.request("GET", "/v1/me")
+                if not me.get("api_key"):
+                    raise ValueError("relaya: pass org_id when using a session token instead of an API key")
+                self._org_id = me["api_key"]["org_id"]
+            return self._org_id
+
+    def request(self, method: str, path: str, body: Any = None, params: Optional[Dict[str, Any]] = None) -> Any:
+        """Low-level request; paths start with /v1. Returns the decoded JSON (None for 204)."""
+        url = self.base_url + path
+        query = _clean(params or {})
+        if query:
+            url += "?" + urllib.parse.urlencode(query)
+        data = None if body is None else json.dumps(body).encode()
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+            "User-Agent": f"relaya-python/{__version__}",
+        }
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        retries = self.max_retries if method == "GET" else 0
+
+        attempt = 0
+        while True:
+            req = urllib.request.Request(url, data=data, headers=headers, method=method)
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                    raw = res.read()
+                    return json.loads(raw) if raw else None
+            except urllib.error.HTTPError as e:
+                raw = e.read()
+                if (e.code == 429 or e.code >= 500) and attempt < retries:
+                    time.sleep(_backoff(attempt, e.headers.get("Retry-After")))
+                    attempt += 1
+                    continue
+                code, message = "http_error", f"HTTP {e.code}"
+                try:
+                    err = json.loads(raw).get("error") or {}
+                    code, message = err.get("code", code), err.get("message", message)
+                except (ValueError, AttributeError):
+                    pass
+                raise RelayaError(e.code, code, message, e.headers.get("X-Request-Id")) from None
+            except (urllib.error.URLError, socket.timeout, TimeoutError, ConnectionError) as e:
+                if attempt < retries:
+                    time.sleep(_backoff(attempt, None))
+                    attempt += 1
+                    continue
+                reason = getattr(e, "reason", e)
+                timed_out = isinstance(reason, (socket.timeout, TimeoutError))
+                raise RelayaError(
+                    0,
+                    "timeout" if timed_out else "network_error",
+                    f"Request timed out after {self.timeout}s" if timed_out else f"Could not reach Relaya: {reason}",
+                ) from None
+
+    def _org(self, method: str, path: str, body: Any = None, params: Optional[Dict[str, Any]] = None) -> Any:
+        return self.request(method, f"/v1/orgs/{self.org_id}{path}", body, params)
+
+
+class _Resource:
+    def __init__(self, client: Relaya) -> None:
+        self._c = client
+
+
+class Projects(_Resource):
+    def list(self) -> List[JSON]:
+        return self._c._org("GET", "/projects")["data"]
+
+    def get(self, id: str) -> JSON:
+        return self._c._org("GET", f"/projects/{id}")
+
+    def create(self, name: str) -> JSON:
+        return self._c._org("POST", "/projects", {"name": name})
+
+
+class Webhooks(_Resource):
+    def list(self, project_id: Optional[str] = None) -> List[JSON]:
+        return self._c._org("GET", "/webhooks", params={"project_id": project_id})["data"]
+
+    def get(self, id: str) -> JSON:
+        return self._c._org("GET", f"/webhooks/{id}")
+
+    def create(self, project_id: str, name: str, provider: str = "generic", **fields: Any) -> JSON:
+        """Create an inbound webhook; give its ``ingest_url`` to the provider.
+        Optional: signing_secret, signature_header."""
+        return self._c._org("POST", "/webhooks", {"project_id": project_id, "name": name, "provider": provider, **fields})
+
+    def update(self, id: str, **fields: Any) -> JSON:
+        """Fields: name, status ("active"/"paused"), signing_secret, signature_header."""
+        return self._c._org("PATCH", f"/webhooks/{id}", fields)
+
+    def rotate_url(self, id: str) -> JSON:
+        """Issue a new ingest URL; the old one stops working."""
+        return self._c._org("POST", f"/webhooks/{id}/rotate-url")
+
+    def delete(self, id: str) -> None:
+        self._c._org("DELETE", f"/webhooks/{id}")
+
+
+class Events(_Resource):
+    def list(self, **filters: Any) -> JSON:
+        """One page, newest first: ``{"data": [...], "next_cursor": ...}``.
+
+        Filters: project_id, webhook_id, type, status, signature, contract_status, dedup_key,
+        since, until (datetime or RFC 3339), limit (1-200), cursor.
+        """
+        return self._c._org("GET", "/events", params=filters)
+
+    def iterate(self, **filters: Any) -> Iterator[JSON]:
+        """Every matching event, newest first, fetching pages as you go."""
+        filters.pop("cursor", None)
+        cursor = None
+        while True:
+            page = self.list(**filters, cursor=cursor)
+            yield from page["data"]
+            cursor = page.get("next_cursor")
+            if not cursor:
+                return
+
+    def get(self, id: str) -> JSON:
+        """Full event: payload (sensitive fields masked), headers, deliveries and contract findings."""
+        return self._c._org("GET", f"/events/{id}")
+
+
+class Destinations(_Resource):
+    def list(self, webhook_id: str) -> List[JSON]:
+        return self._c._org("GET", f"/webhooks/{webhook_id}/destinations")["data"]
+
+    def create(self, webhook_id: str, name: str, url: str, **fields: Any) -> JSON:
+        """Returns ``{"destination": ..., "signing_secret": ...}``. The secret is shown once.
+        Optional: max_attempts, timeout_ms, enabled."""
+        return self._c._org("POST", f"/webhooks/{webhook_id}/destinations", {"name": name, "url": url, **fields})
+
+    def update(self, id: str, **fields: Any) -> JSON:
+        return self._c._org("PATCH", f"/destinations/{id}", fields)
+
+    def delete(self, id: str) -> None:
+        self._c._org("DELETE", f"/destinations/{id}")
+
+    def rotate_secret(self, id: str) -> str:
+        return self._c._org("POST", f"/destinations/{id}/rotate-secret")["signing_secret"]
+
+    def test(self, id: str) -> JSON:
+        """Send a signed test request now; returns ``{ok, status_code, duration_ms, response_body, error}``."""
+        return self._c._org("POST", f"/destinations/{id}/test")
+
+
+class Deliveries(_Resource):
+    def list(self, **filters: Any) -> List[JSON]:
+        """The latest 100 matching deliveries. Filters: event_id, destination_id, webhook_id, status."""
+        return self._c._org("GET", "/deliveries", params=filters)["data"]
+
+    def get(self, id: str) -> JSON:
+        """``{"delivery": ..., "attempts": [...]}``"""
+        return self._c._org("GET", f"/deliveries/{id}")
+
+    def retry(self, id: str) -> JSON:
+        """Send a failed or retrying delivery again now."""
+        return self._c._org("POST", f"/deliveries/{id}/retry")
+
+
+class Contracts(_Resource):
+    def list(self, webhook_id: Optional[str] = None) -> List[JSON]:
+        return self._c._org("GET", "/contracts", params={"webhook_id": webhook_id})["data"]
+
+    def get(self, id: str) -> JSON:
+        return self._c._org("GET", f"/contracts/{id}")
+
+    def create_version(self, id: str, critical_fields: Optional[List[str]] = None, source: str = "observed") -> int:
+        """Activate a new version: from what was ``observed``, or the ``active`` one with new critical fields.
+        Returns the version number."""
+        body: JSON = {"source": source}
+        if critical_fields is not None:
+            body["critical_fields"] = critical_fields
+        return self._c._org("POST", f"/contracts/{id}/versions", body)["version"]
+
+    def relearn(self, id: str) -> None:
+        """Throw away what was learned and start learning again."""
+        self._c._org("POST", f"/contracts/{id}/relearn")
+
+
+class Incidents(_Resource):
+    def list(self, status: Optional[str] = None) -> List[JSON]:
+        """status: "open" (default) or "resolved"."""
+        return self._c._org("GET", "/incidents", params={"status": status})["data"]
+
+    def resolve(self, id: str, resolution: str) -> None:
+        self._c._org("POST", f"/incidents/{id}/resolve", {"resolution": resolution})
+
+    def preview_replay(self, id: str) -> JSON:
+        """Dry run: which events and deliveries a replay would resend. Changes nothing."""
+        return self._c._org("GET", f"/incidents/{id}/replay")
+
+    def replay(self, id: str) -> JSON:
+        """Resend the incident's deliveries. The incident resolves itself if all of them succeed."""
+        return self._c._org("POST", f"/incidents/{id}/replay", {"confirm": True})
+
+
+class Alerts(_Resource):
+    def channels(self) -> List[JSON]:
+        return self._c._org("GET", "/alert-channels")["data"]
+
+    def log(self) -> List[JSON]:
+        return self._c._org("GET", "/alerts")["data"]

relaya-0.1.0/src/relaya/errors.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+class RelayaError(Exception):
+    """An error response from the Relaya API."""
+
+    def __init__(self, status: int, code: str, message: str, request_id: Optional[str] = None) -> None:
+        super().__init__(message)
+        #: HTTP status, or 0 when no response arrived.
+        self.status = status
+        #: e.g. "not_found", "bad_request", "network_error", "timeout".
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+
+    def __str__(self) -> str:
+        return self.message if self.status == 0 else f"{self.status} {self.code}: {self.message}"
+
+
+class WebhookVerificationError(Exception):
+    """A request claiming to come from Relaya failed signature verification.
+
+    ``reason`` is one of: missing_signature, malformed_signature, timestamp_out_of_range, signature_mismatch.
+    """
+
+    def __init__(self, reason: str, message: str) -> None:
+        super().__init__(message)
+        self.reason = reason

relaya-0.1.0/src/relaya/webhooks.py

@@ -0,0 +1,164 @@
+"""Verify requests Relaya forwards to your endpoints."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Mapping, Optional, Sequence, Union
+
+from .errors import WebhookVerificationError
+
+HEADER_SIGNATURE = "Relaya-Signature"
+HEADER_IDEMPOTENCY_KEY = "Idempotency-Key"
+HEADER_EVENT_ID = "Relaya-Event-Id"
+HEADER_DELIVERY_ID = "Relaya-Delivery-Id"
+HEADER_ATTEMPT = "Relaya-Attempt"
+HEADER_REPLAY = "Relaya-Replay"
+HEADER_EVENT_TYPE = "Relaya-Event-Type"
+
+#: Reject signatures older (or newer) than this many seconds by default.
+DEFAULT_TOLERANCE = 300
+
+Body = Union[bytes, bytearray, memoryview, str]
+Secrets = Union[str, Sequence[str]]
+
+
+def _bytes(body: Body) -> bytes:
+    if isinstance(body, str):
+        return body.encode("utf-8")
+    if isinstance(body, (bytes, bytearray, memoryview)):
+        return bytes(body)
+    raise TypeError(
+        "relaya: pass the raw request body (bytes or str), not parsed JSON. "
+        "Django: request.body, Flask: request.get_data(), FastAPI: await request.body()"
+    )
+
+
+def _header(headers: Mapping[str, Any], name: str) -> Optional[str]:
+    value = headers.get(name)
+    if value is None:
+        lower = name.lower()
+        for k, v in headers.items():
+            if k.lower() == lower or k.upper() == "HTTP_" + lower.upper().replace("-", "_"):
+                value = v
+                break
+    if isinstance(value, (list, tuple)):
+        value = value[0] if value else None
+    return None if value is None else str(value)
+
+
+def verify_signature(
+    body: Body,
+    signature_header: Optional[str],
+    secret: Secrets,
+    tolerance: int = DEFAULT_TOLERANCE,
+    now: Optional[float] = None,
+) -> datetime:
+    """Check a ``Relaya-Signature`` header (``t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<body>")>``).
+
+    ``secret`` may be a list while rotating (any match passes). ``tolerance=0`` disables the age check.
+    Returns when the request was signed; raises :class:`WebhookVerificationError`.
+    """
+    secrets = [secret] if isinstance(secret, str) else [s for s in secret]
+    secrets = [s for s in secrets if s]
+    if not secrets:
+        raise ValueError("relaya: a signing secret is required")
+    if not signature_header:
+        raise WebhookVerificationError("missing_signature", "The Relaya-Signature header is missing")
+
+    timestamp: Optional[int] = None
+    signatures = []
+    for part in signature_header.split(","):
+        key, _, value = part.strip().partition("=")
+        if key == "t":
+            try:
+                timestamp = int(value)
+            except ValueError:
+                timestamp = None
+        elif key == "v1" and value:
+            signatures.append(value.lower())
+    if timestamp is None or not signatures:
+        raise WebhookVerificationError("malformed_signature", "The Relaya-Signature header is malformed")
+
+    current = time.time() if now is None else now
+    if tolerance > 0 and abs(current - timestamp) > tolerance:
+        raise WebhookVerificationError(
+            "timestamp_out_of_range", f"The signature is older than {tolerance} seconds (or from the future)"
+        )
+
+    signed = f"{timestamp}.".encode() + _bytes(body)
+    for s in secrets:
+        expected = hmac.new(s.encode("utf-8"), signed, hashlib.sha256).hexdigest()
+        if any(hmac.compare_digest(expected, sig) for sig in signatures):
+            return datetime.fromtimestamp(timestamp, tz=timezone.utc)
+    raise WebhookVerificationError(
+        "signature_mismatch", "The signature does not match: check the signing secret and that you pass the raw body"
+    )
+
+
+def is_valid_signature(body: Body, signature_header: Optional[str], secret: Secrets, **kwargs: Any) -> bool:
+    """Like :func:`verify_signature` but returns True/False."""
+    try:
+        verify_signature(body, signature_header, secret, **kwargs)
+        return True
+    except WebhookVerificationError:
+        return False
+
+
+@dataclass(frozen=True)
+class Delivery:
+    """A verified request forwarded by Relaya."""
+
+    #: The same across retries and replays of one delivery: dedupe on this.
+    idempotency_key: str
+    delivery_id: str
+    event_id: str
+    #: e.g. "payment.captured", when Relaya could tell.
+    event_type: Optional[str]
+    #: 1 for the first try, then 2, 3… on retries.
+    attempt: int
+    #: Set when the request is part of an incident replay.
+    replay_id: Optional[str]
+    signed_at: datetime
+    #: The provider's original body, byte for byte.
+    body: bytes = field(repr=False)
+
+    def json(self) -> Any:
+        return json.loads(self.body)
+
+
+def verify_delivery(body: Body, headers: Mapping[str, Any], secret: Secrets, **kwargs: Any) -> Delivery:
+    """Verify a request forwarded by Relaya and return its details.
+
+    ``headers`` can be Django's ``request.headers`` (or ``request.META``), Flask's or FastAPI's ``request.headers``,
+    or a plain dict.
+    """
+    raw = _bytes(body)
+    signed_at = verify_signature(raw, _header(headers, HEADER_SIGNATURE), secret, **kwargs)
+    delivery_id = _header(headers, HEADER_DELIVERY_ID) or ""
+    try:
+        attempt = max(1, int(_header(headers, HEADER_ATTEMPT) or 1))
+    except ValueError:
+        attempt = 1
+    return Delivery(
+        idempotency_key=_header(headers, HEADER_IDEMPOTENCY_KEY) or delivery_id,
+        delivery_id=delivery_id,
+        event_id=_header(headers, HEADER_EVENT_ID) or "",
+        event_type=_header(headers, HEADER_EVENT_TYPE),
+        attempt=attempt,
+        replay_id=_header(headers, HEADER_REPLAY),
+        signed_at=signed_at,
+        body=raw,
+    )
+
+
+def verify_alert(body: Body, headers: Mapping[str, Any], secret: Secrets, **kwargs: Any) -> dict:
+    """Verify an alert sent to a webhook alert channel and return it:
+    ``{type, title, body, link, org_id, alert_id, sent_at}``."""
+    raw = _bytes(body)
+    verify_signature(raw, _header(headers, HEADER_SIGNATURE), secret, **kwargs)
+    return json.loads(raw)

relaya-0.1.0/src/relaya.egg-info/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: relaya
+Version: 0.1.0
+Summary: Verify webhooks forwarded by Relaya and call the Relaya API.
+License: MIT
+Project-URL: Homepage, https://github.com/Dhirajrai12/relaya-sdks/tree/main/python
+Project-URL: Source, https://github.com/Dhirajrai12/relaya-sdks
+Keywords: relaya,webhooks,signature,hmac,integrations
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# relaya (Python)
+
+Verify requests that Relaya forwards to your endpoints, and call the Relaya API. No dependencies; Python 3.9+.
+
+```sh
+pip install relaya
+```
+
+## Receive events
+
+Relaya signs every request it forwards with your destination's signing secret (shown once when you add the destination). Always pass the **raw** body.
+
+### Django
+
+```python
+from django.http import HttpResponse, JsonResponse
+from django.views.decorators.csrf import csrf_exempt
+from django.views.decorators.http import require_POST
+from relaya import verify_delivery, WebhookVerificationError
+
+@csrf_exempt
+@require_POST
+def relaya_webhook(request):
+    try:
+        delivery = verify_delivery(request.body, request.headers, settings.RELAYA_SIGNING_SECRET)
+    except WebhookVerificationError as e:
+        return JsonResponse({"error": e.reason}, status=400)
+    if already_processed(delivery.idempotency_key):
+        return HttpResponse()
+    handle(delivery.json())
+    return HttpResponse()
+```
+
+### Flask
+
+```python
+@app.post("/webhooks/relaya")
+def relaya_webhook():
+    try:
+        delivery = verify_delivery(request.get_data(), request.headers, os.environ["RELAYA_SIGNING_SECRET"])
+    except WebhookVerificationError as e:
+        return {"error": e.reason}, 400
+    handle(delivery.json())
+    return "", 200
+```
+
+### FastAPI
+
+```python
+@app.post("/webhooks/relaya")
+async def relaya_webhook(request: Request):
+    try:
+        delivery = verify_delivery(await request.body(), request.headers, os.environ["RELAYA_SIGNING_SECRET"])
+    except WebhookVerificationError as e:
+        raise HTTPException(400, e.reason)
+    await handle(delivery.json())
+```
+
+Return a 5xx and Relaya retries later with the same idempotency key.
+
+| `Delivery` field | |
+|---|---|
+| `idempotency_key` | The same across retries and replays of one delivery. Dedupe on this. |
+| `event_id`, `delivery_id` | Relaya's IDs. |
+| `event_type` | e.g. `payment.captured`, when Relaya could tell. |
+| `attempt` | 1, then 2, 3… on retries. |
+| `replay_id` | Set when the request is part of an incident replay. |
+| `body`, `json()` | The provider's original body, unchanged. |
+
+`e.reason` is one of `missing_signature`, `malformed_signature`, `timestamp_out_of_range`, `signature_mismatch`. Pass a list of secrets while rotating; `tolerance=` sets the maximum signature age in seconds (default 300, `0` disables). Webhook alert channels: `verify_alert(body, headers, secret)`.
+
+## Call the API
+
+```python
+from datetime import datetime, timedelta, timezone
+from relaya import Relaya
+
+relaya = Relaya()  # reads RELAYA_API_KEY
+
+for event in relaya.events.iterate(contract_status="breaking", since=datetime.now(timezone.utc) - timedelta(days=7)):
+    print(event["type"], event["received_at"])
+
+for d in relaya.deliveries.list(status="failed"):
+    relaya.deliveries.retry(d["id"])
+
+for incident in relaya.incidents.list("open"):
+    plan = relaya.incidents.preview_replay(incident["id"])  # dry run
+    relaya.incidents.replay(incident["id"])                 # resolves itself once every delivery succeeds
+```
+
+Resources: `projects`, `webhooks`, `events` (`list`, `iterate`, `get`), `destinations`, `deliveries`, `contracts`, `incidents`, `alerts`. Responses are dicts with the API's field names. `relaya.request(method, path, body, params)` reaches anything else.
+
+Options: `api_key` (or `RELAYA_API_KEY`), `base_url` (or `RELAYA_BASE_URL`), `org_id` (only with a session token), `timeout` (30 s), `max_retries` (2; GET only, on network errors, 429 and 5xx).
+
+Errors raise `RelayaError` with `status`, `code` and `request_id`.
+
+## Development
+
+```sh
+PYTHONPATH=src python -m unittest discover -s tests
+RELAYA_IT_API_URL=http://127.0.0.1:18080 PYTHONPATH=src python -m unittest tests.test_integration   # against a running dev stack
+```

relaya-0.1.0/src/relaya.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/relaya/__init__.py
+src/relaya/client.py
+src/relaya/errors.py
+src/relaya/py.typed
+src/relaya/webhooks.py
+src/relaya.egg-info/PKG-INFO
+src/relaya.egg-info/SOURCES.txt
+src/relaya.egg-info/dependency_links.txt
+src/relaya.egg-info/top_level.txt
+tests/test_client.py
+tests/test_integration.py
+tests/test_webhooks.py

relaya-0.1.0/src/relaya.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

relaya-0.1.0/src/relaya.egg-info/top_level.txt

@@ -0,0 +1 @@
+relaya

relaya-0.1.0/tests/test_client.py

@@ -0,0 +1,106 @@
+import json
+import threading
+import unittest
+from datetime import datetime, timezone
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs, urlparse
+
+from relaya import Relaya, RelayaError
+
+
+class FakeAPI:
+    """A tiny HTTP server: routes "METHOD /path" to (status, body, headers) callables."""
+
+    def __init__(self, routes):
+        self.calls = []
+        api = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def log_message(self, *args):
+                pass
+
+            def handle_any(self):
+                u = urlparse(self.path)
+                length = int(self.headers.get("Content-Length") or 0)
+                body = json.loads(self.rfile.read(length)) if length else None
+                call = {"method": self.command, "path": u.path, "query": parse_qs(u.query), "body": body, "auth": self.headers.get("Authorization")}
+                api.calls.append(call)
+                route = routes.get(f"{self.command} {u.path}")
+                n = sum(1 for c in api.calls if c["method"] == self.command and c["path"] == u.path)
+                status, payload, headers = route(call, n) if route else (404, {"error": {"code": "not_found", "message": "no route"}}, {})
+                self.send_response(status)
+                for k, v in headers.items():
+                    self.send_header(k, v)
+                data = b"" if payload is None else json.dumps(payload).encode()
+                self.send_header("Content-Length", str(len(data)))
+                self.end_headers()
+                self.wfile.write(data)
+
+            do_GET = do_POST = do_PATCH = do_DELETE = handle_any
+
+        self.server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        threading.Thread(target=self.server.serve_forever, daemon=True).start()
+        self.url = f"http://127.0.0.1:{self.server.server_address[1]}"
+
+    def close(self):
+        self.server.shutdown()
+
+
+class ClientTest(unittest.TestCase):
+    def api(self, routes):
+        a = FakeAPI(routes)
+        self.addCleanup(a.close)
+        return a
+
+    def test_org_lookup_once_and_auth(self):
+        a = self.api({
+            "GET /v1/me": lambda c, n: (200, {"api_key": {"org_id": "org1"}}, {}),
+            "GET /v1/orgs/org1/projects": lambda c, n: (200, {"data": [{"id": "p1"}]}, {}),
+        })
+        r = Relaya("rk_test", base_url=a.url + "/")
+        self.assertEqual(r.projects.list()[0]["id"], "p1")
+        r.projects.list()
+        self.assertEqual(sum(1 for c in a.calls if c["path"] == "/v1/me"), 1)
+        self.assertTrue(all(c["auth"] == "Bearer rk_test" for c in a.calls))
+
+    def test_filters_and_iterate(self):
+        def events(c, n):
+            if c["query"].get("cursor") == ["c2"]:
+                return 200, {"data": [{"id": "e3"}], "next_cursor": None}, {}
+            return 200, {"data": [{"id": "e1"}, {"id": "e2"}], "next_cursor": "c2"}, {}
+
+        a = self.api({"GET /v1/orgs/o/events": events})
+        r = Relaya("rk", org_id="o", base_url=a.url)
+        ids = [e["id"] for e in r.events.iterate(contract_status="breaking", since=datetime(2026, 9, 1, tzinfo=timezone.utc), limit=2, type=None)]
+        self.assertEqual(ids, ["e1", "e2", "e3"])
+        q = a.calls[0]["query"]
+        self.assertEqual(q["contract_status"], ["breaking"])
+        self.assertEqual(q["since"], ["2026-09-01T00:00:00Z"])
+        self.assertNotIn("type", q)
+
+    def test_errors_and_retries(self):
+        a = self.api({
+            "GET /v1/orgs/o/incidents": lambda c, n: (503, None, {"Retry-After": "0"}) if n < 3 else (200, {"data": []}, {}),
+            "POST /v1/orgs/o/incidents/i1/replay": lambda c, n: (503, None, {"Retry-After": "0"}),
+        })
+        r = Relaya("rk", org_id="o", base_url=a.url)
+        self.assertEqual(r.incidents.list("open"), [])
+        with self.assertRaises(RelayaError) as cm:
+            r.incidents.replay("i1")
+        self.assertEqual(cm.exception.status, 503)
+        posts = [c for c in a.calls if c["method"] == "POST"]
+        self.assertEqual(len(posts), 1)
+        self.assertEqual(posts[0]["body"], {"confirm": True})
+        with self.assertRaises(RelayaError) as cm:
+            r.webhooks.get("nope")
+        self.assertEqual((cm.exception.status, cm.exception.code), (404, "not_found"))
+
+    def test_network_error(self):
+        r = Relaya("rk", org_id="o", base_url="http://127.0.0.1:1", max_retries=0)
+        with self.assertRaises(RelayaError) as cm:
+            r.projects.list()
+        self.assertEqual((cm.exception.status, cm.exception.code), (0, "network_error"))
+
+
+if __name__ == "__main__":
+    unittest.main()

relaya-0.1.0/tests/test_integration.py

@@ -0,0 +1,136 @@
+"""End-to-end against a running Relaya (API + ingest + worker). Skipped unless RELAYA_IT_API_URL is set:
+
+    RELAYA_IT_API_URL=http://127.0.0.1:18080 python -m unittest tests.test_integration
+
+The server must allow http://127.0.0.1 destinations (APP_ENV=dev) and use CONTRACT_MIN_SAMPLES=3.
+"""
+
+import json
+import os
+import threading
+import time
+import unittest
+import urllib.request
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+from relaya import Relaya, RelayaError, WebhookVerificationError, verify_delivery
+
+API = os.environ.get("RELAYA_IT_API_URL")
+
+
+def wait_for(what, fn, timeout=15):
+    until = time.time() + timeout
+    while True:
+        v = fn()
+        if v:
+            return v
+        if time.time() > until:
+            raise AssertionError(f"timed out waiting for {what}")
+        time.sleep(0.15)
+
+
+def post(path, body, token=None):
+    req = urllib.request.Request(API + path, data=json.dumps(body).encode(), method="POST", headers={"Content-Type": "application/json", **({"Authorization": f"Bearer {token}"} if token else {})})
+    with urllib.request.urlopen(req) as r:
+        return json.loads(r.read())
+
+
+@unittest.skipUnless(API, "set RELAYA_IT_API_URL to run")
+class IntegrationTest(unittest.TestCase):
+    def test_sdk_against_live_relaya(self):
+        session = post("/v1/auth/signup", {"email": f"py-sdk-{time.time_ns()}@example.com", "password": "sdk-test-password-1", "org_name": "Python SDK"})
+        org_id = Relaya(session["token"], base_url=API).request("GET", "/v1/me")["orgs"][0]["id"]
+        key = post(f"/v1/orgs/{org_id}/api-keys", {"name": "sdk", "role": "admin"}, session["token"])
+
+        relaya = Relaya(key["key"], base_url=API)
+        self.assertEqual(relaya.org_id, org_id)
+
+        # A customer endpoint verifying with the SDK.
+        state = {"secret": "", "fail_next": 0, "received": []}
+
+        class Endpoint(BaseHTTPRequestHandler):
+            def log_message(self, *a):
+                pass
+
+            def do_POST(self):
+                body = self.rfile.read(int(self.headers["Content-Length"]))
+                try:
+                    d = verify_delivery(body, self.headers, state["secret"])
+                except WebhookVerificationError as e:
+                    self.send_response(400)
+                    self.end_headers()
+                    self.wfile.write(e.reason.encode())
+                    return
+                state["received"].append(d)
+                failing = state["fail_next"] > 0
+                state["fail_next"] -= 1
+                self.send_response(500 if failing else 200)
+                self.end_headers()
+
+        server = ThreadingHTTPServer(("127.0.0.1", 0), Endpoint)
+        threading.Thread(target=server.serve_forever, daemon=True).start()
+        self.addCleanup(server.shutdown)
+        received = state["received"]
+
+        project = relaya.projects.create("SDK")
+        wh = relaya.webhooks.create(project["id"], "Payments", "generic")
+        dest = relaya.destinations.create(wh["id"], "My app", f"http://127.0.0.1:{server.server_address[1]}/hooks")
+        state["secret"] = dest["signing_secret"]
+
+        def send(event_id, body):
+            req = urllib.request.Request(wh["ingest_url"], data=json.dumps(body).encode(), method="POST", headers={"Content-Type": "application/json", "X-Event-Id": event_id})
+            with urllib.request.urlopen(req) as r:
+                self.assertEqual(r.status, 200)
+
+        for i in range(1, 4):
+            send(f"e{i}", {"type": "payment.captured", "amount": 100 * i})
+
+        wait_for("3 deliveries", lambda: len(received) >= 3)
+        first = received[0]
+        self.assertEqual(first.idempotency_key, first.delivery_id)
+        self.assertEqual(first.attempt, 1)
+        self.assertEqual(first.event_type, "payment.captured")
+        self.assertIsInstance(first.json()["amount"], int)
+
+        events = list(relaya.events.iterate(webhook_id=wh["id"], limit=2))
+        self.assertEqual(len(events), 3)
+        self.assertEqual(relaya.events.get(first.event_id)["payload_json"]["type"], "payment.captured")
+
+        ok = wait_for("succeeded deliveries", lambda: (lambda l: len(l) == 3 and l)(relaya.deliveries.list(webhook_id=wh["id"], status="succeeded")))
+        self.assertEqual(relaya.deliveries.get(ok[0]["id"])["attempts"][0]["outcome"], "succeeded")
+
+        # Failing endpoint, then a manual retry.
+        state["fail_next"] = 1
+        send("e4", {"type": "payment.captured", "amount": 400})
+        retrying = wait_for("a retrying delivery", lambda: relaya.deliveries.list(webhook_id=wh["id"], status="retrying"))[0]
+        relaya.deliveries.retry(retrying["id"])
+        wait_for("the retry to succeed", lambda: relaya.deliveries.get(retrying["id"])["delivery"]["status"] == "succeeded")
+        self.assertEqual(received[-1].attempt, 2)
+        self.assertEqual(received[-1].idempotency_key, retrying["id"])
+
+        # Contract -> incident -> replay.
+        contract = wait_for("a proposed contract", lambda: next((c for c in relaya.contracts.list(wh["id"]) if c["status"] != "learning"), None))
+        self.assertGreaterEqual(relaya.contracts.create_version(contract["id"], ["amount"], "observed"), 1)
+        send("e5", {"type": "payment.captured", "amount": "500"})
+        incident = wait_for("an open incident", lambda: relaya.incidents.list("open"))[0]
+        self.assertIn("amount changed type", incident["title"])
+        self.assertEqual(relaya.incidents.preview_replay(incident["id"])["events"], 1)
+        before = len(received)
+        replay = relaya.incidents.replay(incident["id"])
+        self.assertEqual(replay["total"], 1)
+        wait_for("the replayed delivery", lambda: len(received) > before)
+        self.assertEqual(received[-1].replay_id, replay["id"])
+        wait_for("the incident to resolve", lambda: relaya.incidents.list("open") == [])
+
+        # Destination test and API errors.
+        self.assertTrue(relaya.destinations.test(dest["destination"]["id"])["ok"])
+        with self.assertRaises(RelayaError) as cm:
+            relaya.webhooks.get("00000000-0000-0000-0000-000000000000")
+        self.assertEqual(cm.exception.status, 404)
+        with self.assertRaises(RelayaError) as cm:
+            relaya.deliveries.retry(ok[0]["id"])
+        self.assertEqual(cm.exception.status, 409)
+
+
+if __name__ == "__main__":
+    unittest.main()

relaya-0.1.0/tests/test_webhooks.py

@@ -0,0 +1,82 @@
+import hashlib
+import hmac
+import json
+import time
+import unittest
+
+from relaya import WebhookVerificationError, is_valid_signature, verify_alert, verify_delivery, verify_signature
+
+SECRET = "whsec_test_secret"
+BODY = '{"type":"payment.captured","amount":100,"note":"héllo"}'.encode()
+
+
+def sign(body: bytes, secret: str = SECRET, t: int = None) -> str:
+    """Same algorithm as the Relaya worker: hex HMAC-SHA256(secret, "<t>.<body>")."""
+    t = int(time.time()) if t is None else t
+    return f"t={t},v1=" + hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
+
+
+class VerifySignatureTest(unittest.TestCase):
+    def reason(self, *args, **kwargs):
+        with self.assertRaises(WebhookVerificationError) as cm:
+            verify_signature(*args, **kwargs)
+        return cm.exception.reason
+
+    def test_valid_bytes_and_str(self):
+        h = sign(BODY)
+        verify_signature(BODY, h, SECRET)
+        verify_signature(BODY.decode(), h, SECRET)
+        verify_signature(bytearray(BODY), h, SECRET)
+        self.assertTrue(is_valid_signature(BODY, h, SECRET))
+
+    def test_rejections(self):
+        self.assertEqual(self.reason(BODY, sign(BODY, "other"), SECRET), "signature_mismatch")
+        self.assertEqual(self.reason(BODY + b" ", sign(BODY), SECRET), "signature_mismatch")
+        self.assertEqual(self.reason(BODY, None, SECRET), "missing_signature")
+        self.assertEqual(self.reason(BODY, "v1=abc", SECRET), "malformed_signature")
+        self.assertEqual(self.reason(BODY, "t=x,v1=abc", SECRET), "malformed_signature")
+        self.assertFalse(is_valid_signature(BODY, sign(BODY, "other"), SECRET))
+
+    def test_tolerance(self):
+        old = int(time.time()) - 301
+        self.assertEqual(self.reason(BODY, sign(BODY, t=old), SECRET), "timestamp_out_of_range")
+        verify_signature(BODY, sign(BODY, t=old), SECRET, tolerance=600)
+        verify_signature(BODY, sign(BODY, t=old), SECRET, tolerance=0)
+        at = verify_signature(BODY, sign(BODY, t=1_700_000_000), SECRET, now=1_700_000_005)
+        self.assertEqual(at.timestamp(), 1_700_000_000)
+
+    def test_rotation_and_bad_input(self):
+        verify_signature(BODY, sign(BODY, "new"), ["old", "new"])
+        with self.assertRaises(ValueError):
+            verify_signature(BODY, sign(BODY), [])
+        with self.assertRaisesRegex(TypeError, "raw request body"):
+            verify_signature(json.loads(BODY), sign(BODY), SECRET)
+
+
+class VerifyDeliveryTest(unittest.TestCase):
+    def test_headers_any_case_and_django_meta(self):
+        plain = {
+            "relaya-signature": sign(BODY),
+            "Idempotency-Key": "dlv_1",
+            "RELAYA-DELIVERY-ID": "dlv_1",
+            "Relaya-Event-Id": "evt_1",
+            "Relaya-Attempt": "3",
+            "Relaya-Event-Type": "payment.captured",
+        }
+        meta = {"HTTP_" + k.upper().replace("-", "_"): v for k, v in plain.items()}  # Django request.META
+        for headers in (plain, meta):
+            d = verify_delivery(BODY, headers, SECRET)
+            self.assertEqual(d.idempotency_key, "dlv_1")
+            self.assertEqual(d.event_id, "evt_1")
+            self.assertEqual(d.attempt, 3)
+            self.assertEqual(d.event_type, "payment.captured")
+            self.assertIsNone(d.replay_id)
+            self.assertEqual(d.json()["note"], "héllo")
+
+    def test_alert(self):
+        body = json.dumps({"type": "test", "title": "Test alert", "alert_id": 1}).encode()
+        self.assertEqual(verify_alert(body, {"Relaya-Signature": sign(body)}, SECRET)["title"], "Test alert")
+
+
+if __name__ == "__main__":
+    unittest.main()