paystack-webhook 0.1.1__py3-none-any.whl

paystack_webhook-0.1.1.dist-info/METADATA

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: paystack-webhook
+Version: 0.1.1
+Summary: Verify Paystack and Flutterwave webhooks in Python: HMAC-SHA512, idempotency, replay-safe retries. Zero dependencies.
+Author: mgkvibez
+License: MIT
+Project-URL: Homepage, https://github.com/mgkvibez/paystack-webhooks
+Project-URL: Issues, https://github.com/mgkvibez/paystack-webhooks/issues
+Keywords: paystack,flutterwave,webhooks,payments,africa,nigeria,hmac,fastapi
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: fastapi>=0.110; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: flask>=3.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Dynamic: license-file
+
+# paystack-webhooks
+
+**Verify Paystack and Flutterwave webhooks in Python, including the part the docs skip: retries.**
+
+[![ci](https://github.com/mgkvibez/paystack-webhooks/actions/workflows/ci.yml/badge.svg)](https://github.com/mgkvibez/paystack-webhooks/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](pyproject.toml)
+[![dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](pyproject.toml)
+
+```python
+from paystack_webhooks import PaystackWebhook
+
+paystack = PaystackWebhook("sk_live_...")
+
+event = paystack.process(raw_body, headers)   # None means you already handled it
+```
+
+That is the whole library. The rest of this page is why `process` exists and the
+four-line snippet on Stack Overflow is not enough.
+
+## The snippet everyone copies, and what it misses
+
+```python
+if hmac.new(key, request.body, hashlib.sha512).hexdigest() != request.headers["x-paystack-signature"]:
+    abort(401)
+```
+
+The signature check is right. Two other things are missing, and both cost money.
+
+**1. Retries.** Paystack and Flutterwave both retry when your endpoint does not return
+a 2xx: a timeout, a 500, a deploy that restarts the worker mid-request. Your handler
+then runs twice for one payment. If the second run grants value again, you have given
+away product, and no amount of signature checking prevents it.
+
+**2. Verifying after parsing.** If you call `request.json()` first, the bytes you
+hash are not the bytes that arrived: key order and whitespace change, the digest never
+matches, and the usual "fix" is to drop the check.
+
+This library handles the raw bytes, derives a stable event id, and gives you a
+single call that is safe to repeat.
+
+## Install
+
+```bash
+pipx install paystack-webhook
+```
+
+The distribution is called `paystack-webhook`, singular, because PyPI refused
+`paystack-webhooks` as too similar to a project that already exists. Nothing a user
+types changes: the import is `paystack_webhooks` and the repo keeps its name.
+
+Python 3.9+, **zero runtime dependencies**. FastAPI and Flask are optional extras that
+only the adapters import.
+
+## FastAPI
+
+```python
+from fastapi import FastAPI
+from paystack_webhooks import MemoryStore, PaystackWebhook
+from paystack_webhooks.contrib.fastapi import webhook_route
+
+app = FastAPI()
+
+def on_event(event):
+    if event.name == "charge.success":
+        fulfil(event.data["reference"], event.data["amount"])
+
+app.include_router(webhook_route(
+    PaystackWebhook("sk_live_..."),
+    store=MemoryStore(),          # dedupe across retries
+    on_event=on_event,
+    path="/webhooks/paystack",
+))
+```
+
+Duplicates return **200**, not 409. Both providers retry on non-2xx, so answering
+409 to something you already handled starts a retry storm.
+
+## Flask
+
+```python
+from flask import Flask
+from paystack_webhooks import MemoryStore, PaystackWebhook
+from paystack_webhooks.contrib.flask import webhook_view
+
+app = Flask(__name__)
+app.add_url_rule("/webhooks/paystack", methods=["POST"], view_func=webhook_view(
+    PaystackWebhook("sk_live_..."), store=MemoryStore(), on_event=on_event))
+```
+
+Anywhere else, the core is framework-agnostic: pass the raw bytes and a header mapping
+you can read case-insensitively.
+
+## Flutterwave, and the weaker guarantee it actually offers
+
+```python
+from paystack_webhooks import FlutterwaveWebhook
+
+flutterwave = FlutterwaveWebhook("your_verif_hash")
+event = flutterwave.process(raw_body, headers)
+```
+
+Flutterwave does not sign the body. It sends your static secret in a `verif-hash`
+header, which proves the sender knows the hash and nothing else. A valid header can
+accompany a tampered payload if the hash leaks. This library says so instead of
+implying parity with Paystack.
+
+## The security model, stated plainly
+
+| | Paystack | Flutterwave |
+|---|---|---|
+| What is checked | HMAC-SHA512 over the raw body | static `verif-hash` header |
+| Does it cover the body | yes | **no** |
+| Signed timestamp | none | none |
+| Replay defence | dedupe on `event_id` | dedupe, plus compare amount and currency |
+
+Neither provider sends a signed timestamp, so a "5 minute replay window" is theatre:
+there is nothing authentic to compare a clock against. Deduplication is the only
+honest defence available, which is why `event_id` is computed for you and why the store
+is part of the API.
+
+For Flutterwave, always compare `event.data["amount"]` and `currency` against your own
+record before fulfilling. The header cannot tell you the amount is right.
+
+## What this deliberately does not do
+
+- **It is not an API client.** Use `paystackapi` or `rave-python` to charge cards. This
+  library only consumes webhooks.
+- **It does not validate amounts for you.** That requires your records, not the payload.
+- **`MemoryStore` is single-process.** It is correct for one worker. On several
+  instances implement the four-line `Store` protocol against Redis or a table with a
+  unique constraint; a check-then-insert will race and double-charge.
+- **It does not decide your response codes for unknown events.** The adapter returns
+  200 and calls your handler; ignore event types you do not care about.
+
+## Errors map to status codes
+
+| Exception | Meaning | Status |
+|---|---|---|
+| `SignatureError` | wrong secret, forged header, tampered body | 401 |
+| `MalformedPayload` | valid signature, unusable body | 400 |
+| `RawBodyRequired` | you passed text or a dict instead of bytes | 500, and it is a bug in your code |
+
+## Tests
+
+The suite runs offline: signatures are computed in the tests with `hmac`/`hashlib`
+directly, so a bug in this library cannot make its own tests pass. It covers valid and
+forged signatures, tampered bodies, non-ASCII headers, text bodies, validly signed
+garbage, idempotency including a 50-thread race on one event id, TTL and capacity
+eviction, both adapters, and a check that importing the core pulls in no web framework.
+
+```bash
+pip install -e ".[dev]"
+python -m pytest -q
+bash scripts/verify.sh
+```
+
+## License
+
+MIT.

paystack_webhook-0.1.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+paystack_webhook-0.1.1.dist-info/licenses/LICENSE,sha256=e-0Bks6hOWW2m30Xgh8w6CENzPJoV246vIq2lz_9Ing,1065
+paystack_webhooks/__init__.py,sha256=1JnHwmX0HaIC8qesYapY9V2kH81anVVKFNs46tt_-4A,740
+paystack_webhooks/errors.py,sha256=2qo0cRGZzoaphltCFtmyIg7079Y36A2XF_u3HeBCY7g,1501
+paystack_webhooks/event.py,sha256=FPm3HjAtp9MwhqH6c-d71xaH3_3OfezVw04bSdXK2H8,3257
+paystack_webhooks/flutterwave.py,sha256=yOq2Cuw-25F5zQbwqAJgn9imBSz16URvvRWXQ5HDjek,3120
+paystack_webhooks/idempotency.py,sha256=NNquNqtLcq8FWR8y3faKf2Syf0Edsp11my3ccdhatEQ,2318
+paystack_webhooks/paystack.py,sha256=vBV8izLFGhBaJ0zIAqLNC-kSBBw_YIbX9XFmqlbwyeU,3209
+paystack_webhooks/signature.py,sha256=g2ZOO-4VJI4J0SngRp1ARFfwETEPu-G18tenSFaOmM8,1051
+paystack_webhooks/contrib/__init__.py,sha256=8a3TnD92BD2I4ixq4ywotd34Na9Om6tW81-n5sN9N98,73
+paystack_webhooks/contrib/fastapi.py,sha256=tyidtkMRSlQZR-B8c_id8igXfq4v8fJKsjGa9d-9vnA,1703
+paystack_webhooks/contrib/flask.py,sha256=8N2-SsCuPHfdTWYwUeP1zzTcTPSUupbj_tAiBU-jcVM,1283
+paystack_webhook-0.1.1.dist-info/METADATA,sha256=1we0dP3972v_DNC7IRCYOwiD3P-9jQ1SpnUmU49NqUE,7234
+paystack_webhook-0.1.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+paystack_webhook-0.1.1.dist-info/top_level.txt,sha256=C5etboHWn3owvC4ZYmZR3fCCRTaTr-hUujmjBGSiQJ4,18
+paystack_webhook-0.1.1.dist-info/RECORD,,

paystack_webhook-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

paystack_webhook-0.1.1.dist-info/licenses/LICENSE

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

paystack_webhook-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+paystack_webhooks

paystack_webhooks/__init__.py

@@ -0,0 +1,28 @@
+"""Verify Paystack and Flutterwave webhooks without getting it wrong.
+
+    from paystack_webhooks import PaystackWebhook, MemoryStore
+
+    paystack = PaystackWebhook("sk_live_...")
+    event = paystack.process(raw_body, headers)   # None means already handled
+"""
+
+from .errors import MalformedPayload, RawBodyRequired, SignatureError, WebhookError
+from .event import Event
+from .flutterwave import FlutterwaveWebhook
+from .idempotency import MemoryStore, Store
+from .paystack import PaystackWebhook
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "Event",
+    "FlutterwaveWebhook",
+    "MalformedPayload",
+    "MemoryStore",
+    "PaystackWebhook",
+    "RawBodyRequired",
+    "SignatureError",
+    "Store",
+    "WebhookError",
+    "__version__",
+]

paystack_webhooks/contrib/__init__.py

@@ -0,0 +1 @@
+"""Framework adapters. Importing this package pulls in nothing heavy."""

paystack_webhooks/contrib/fastapi.py

@@ -0,0 +1,46 @@
+"""Mount a verified webhook route in four lines.
+
+    app.include_router(webhook_route(PaystackWebhook(secret), store=MemoryStore()))
+
+Duplicates return 200 on purpose. Paystack retries on any non-2xx, so answering
+409 to a duplicate starts a retry storm for an event you already handled.
+"""
+
+import inspect
+from typing import Awaitable, Callable, Optional, Union
+
+from fastapi import APIRouter, HTTPException, Request
+
+from ..errors import MalformedPayload, RawBodyRequired, SignatureError
+from ..event import Event
+from ..idempotency import Store
+
+Handler = Callable[[Event], Union[None, Awaitable[None]]]
+
+
+def webhook_route(verifier, *, store: Optional[Store] = None,
+                  on_event: Optional[Handler] = None, path: str = "/webhooks/paystack"):
+    router = APIRouter()
+
+    @router.post(path)
+    async def receive(request: Request) -> dict:
+        body = await request.body()
+        try:
+            event = verifier.parse(body, request.headers)
+        except RawBodyRequired as exc:
+            raise HTTPException(status_code=500, detail=str(exc)) from exc
+        except SignatureError as exc:
+            raise HTTPException(status_code=401, detail="invalid signature") from exc
+        except MalformedPayload as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+        if store is not None and store.seen(event.event_id):
+            return {"status": "duplicate", "event_id": event.event_id}
+
+        if on_event is not None:
+            result = on_event(event)
+            if inspect.isawaitable(result):
+                await result
+        return {"status": "accepted", "event": event.name, "event_id": event.event_id}
+
+    return router

paystack_webhooks/contrib/flask.py

@@ -0,0 +1,38 @@
+"""Flask view factory for verified webhooks.
+
+    app.add_url_rule("/webhooks/paystack", view_func=webhook_view(verifier), methods=["POST"])
+
+Flask gives you `request.get_data()` for the raw bytes. Do not use `request.json`:
+by then the bytes are gone and the digest cannot match.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ..errors import MalformedPayload, RawBodyRequired, SignatureError
+from ..idempotency import Store
+
+
+def webhook_view(verifier, *, store: Optional[Store] = None, on_event=None):
+    from flask import jsonify, request
+
+    def view():
+        body = request.get_data(cache=True)
+        try:
+            event = verifier.parse(body, request.headers)
+        except RawBodyRequired as exc:
+            return jsonify({"error": str(exc)}), 500
+        except SignatureError:
+            return jsonify({"error": "invalid signature"}), 401
+        except MalformedPayload as exc:
+            return jsonify({"error": str(exc)}), 400
+
+        if store is not None and store.seen(event.event_id):
+            return jsonify({"status": "duplicate", "event_id": event.event_id}), 200
+
+        if on_event is not None:
+            on_event(event)
+        return jsonify({"status": "accepted", "event": event.name}), 200
+
+    return view

paystack_webhooks/errors.py

@@ -0,0 +1,39 @@
+"""Typed failures, so a caller can tell a forged request from a broken one.
+
+A 401 and a 400 are different problems for whoever is on call: one means someone
+is posting to your endpoint with the wrong secret, the other means the payload is
+not what the provider promised. Collapsing them into one exception makes that
+distinction impossible to recover.
+"""
+
+
+class WebhookError(Exception):
+    """Base class for everything this library raises."""
+
+
+class SignatureError(WebhookError):
+    """The request did not carry a valid signature for the configured secret.
+
+    Treat this as hostile until proven otherwise. Never retry-and-hope on it, and
+    never log the provided header value at info level: a wrong secret is usually a
+    deployment mistake, but a valid-looking header with a bad digest is a forgery
+    attempt and its contents are attacker-controlled.
+    """
+
+
+class MalformedPayload(WebhookError):
+    """The signature was valid but the body is not a usable webhook event.
+
+    A valid signature over garbage still means the provider sent garbage, so this
+    is a 400, not a 401.
+    """
+
+
+class RawBodyRequired(WebhookError, TypeError):
+    """The body arrived as text instead of bytes, so it cannot be verified.
+
+    Re-serialising parsed JSON changes key order and whitespace, which changes the
+    digest. This is the single most common way a correct signature check gets
+    written and still fails in production, so it is a named error rather than a
+    silent coercion.
+    """

paystack_webhooks/event.py

@@ -0,0 +1,96 @@
+"""One incoming event, verified, with a stable id for deduplication."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+
+def _digest(raw: bytes) -> str:
+    return hashlib.sha256(raw).hexdigest()[:32]
+
+
+@dataclass(frozen=True)
+class Event:
+    """A verified webhook delivery.
+
+    ``event_id`` is what you store to make retries harmless. Both providers retry
+    on any non-2xx response, and neither sends a signed timestamp, so a delivery
+    cannot be proven fresh by cryptography. Deduplicating on this id is the only
+    honest replay defence available, which is why it is computed here rather than
+    left to the caller.
+    """
+
+    provider: str
+    name: str
+    data: Mapping[str, Any]
+    event_id: str
+    raw: bytes = field(repr=False, default=b"")
+    headers: Mapping[str, str] = field(repr=False, default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.name:
+            raise ValueError("an event needs a name")
+
+    def to_dict(self) -> dict:
+        return {
+            "provider": self.provider,
+            "name": self.name,
+            "event_id": self.event_id,
+            "data": dict(self.data),
+        }
+
+
+def build_event(provider: str, payload: Mapping[str, Any], raw: bytes,
+                headers: Mapping[str, str]) -> Event:
+    """Turn a parsed payload into an Event, deriving a dedupe id you can trust.
+
+    Preference order for the id: the provider's own record id, then a hash of the
+    exact bytes. The hash fallback means an event with no id is still deduplicated
+    rather than silently allowed to double-process.
+    """
+    name = str(payload.get("event") or payload.get("event_type") or "").strip()
+    data = payload.get("data")
+    if not isinstance(data, Mapping):
+        data = {}
+
+    record_id = data.get("id")
+    if record_id is None:
+        record_id = payload.get("id")
+    if record_id is not None and str(record_id).strip():
+        event_id = "%s:%s:%s" % (provider, name or "event", record_id)
+    else:
+        event_id = "%s:%s:sha256:%s" % (provider, name or "event", _digest(raw))
+
+    return Event(provider=provider, name=name, data=data, event_id=event_id,
+                 raw=raw, headers=dict(headers or {}))
+
+
+def header(headers: Mapping[str, str], name: str) -> str:
+    """Case-insensitive header lookup that works for dicts and Starlette's Headers."""
+    if not headers:
+        return ""
+    try:
+        value = headers.get(name)  # type: ignore[union-attr]
+        if value is not None:
+            return str(value)
+    except AttributeError:
+        pass
+    lowered = name.lower()
+    for key, value in headers.items():
+        if str(key).lower() == lowered:
+            return "" if value is None else str(value)
+    return ""
+
+
+def load_json(raw: bytes) -> Mapping[str, Any]:
+    """Parse the body into an object, or raise MalformedPayload via the caller."""
+    try:
+        payload = json.loads(raw)
+    except (ValueError, UnicodeDecodeError) as exc:
+        raise ValueError("body is not JSON: %s" % exc.__class__.__name__) from exc
+    if not isinstance(payload, Mapping):
+        raise ValueError("body is JSON but not an object")
+    return payload

paystack_webhooks/flutterwave.py

@@ -0,0 +1,71 @@
+"""Flutterwave webhooks.
+
+Flutterwave does not sign the payload. It sends your configured secret hash in the
+``verif-hash`` header, and the only thing that proves is that the sender knows the
+hash. It does **not** cover the body, so a valid header can accompany a tampered
+payload if the hash ever leaks.
+
+That is a weaker guarantee than Paystack's, and pretending otherwise would be
+dishonest. Practical implications, documented rather than hidden:
+
+* Rotate the hash if it is exposed anywhere (logs, a public repo, a screenshot).
+* Deduplicate on ``event_id``; the hash is static, so it cannot prevent replay.
+* Compare the transaction amount and currency against your own record before
+  fulfilling. The signature cannot tell you the amount is right, only that the
+  sender knows the secret.
+"""
+
+from __future__ import annotations
+
+from typing import Mapping, Optional
+
+from .errors import MalformedPayload, RawBodyRequired, SignatureError
+from .event import Event, build_event, header, load_json
+from .idempotency import Store
+from .signature import constant_time_equals
+
+VERIF_HASH_HEADER = "verif-hash"
+PROVIDER = "flutterwave"
+
+
+class FlutterwaveWebhook:
+    """Verify and decode Flutterwave webhook deliveries."""
+
+    def __init__(self, secret_hash: str, *, store: Optional[Store] = None) -> None:
+        if not secret_hash or not str(secret_hash).strip():
+            raise ValueError(
+                "secret_hash is required: pass the hash you set in the Flutterwave dashboard")
+        self._hash = str(secret_hash).strip()
+        self._store = store
+
+    def parse(self, body: bytes, headers: Mapping[str, str]) -> Event:
+        if isinstance(body, str):
+            raise RawBodyRequired(
+                "body arrived as str, which cannot be verified: re-encoding changes the "
+                "digest. Pass the raw bytes instead (request.body(), request.get_data()).")
+        if isinstance(body, (bytearray, memoryview)):
+            body = bytes(body)
+        if not isinstance(body, bytes):
+            raise RawBodyRequired(
+                "body must be raw bytes; pass request.body() before parsing JSON")
+        provided = header(headers, VERIF_HASH_HEADER)
+        # Deliberately no body in this comparison: Flutterwave's hash is static.
+        if not constant_time_equals(self._hash, provided):
+            raise SignatureError("verif-hash did not match the configured secret hash")
+        try:
+            payload = load_json(body)
+        except ValueError as exc:
+            raise MalformedPayload(str(exc)) from exc
+        if not str(payload.get("event") or payload.get("event_type") or "").strip():
+            raise MalformedPayload("payload has no 'event' field")
+        return build_event(PROVIDER, payload, body, headers or {})
+
+    def process(self, body: bytes, headers: Mapping[str, str],
+                *, store: Optional[Store] = None) -> Optional[Event]:
+        event = self.parse(body, headers)
+        target = store if store is not None else self._store
+        if target is not None and target.seen(event.event_id):
+            return None
+        return event
+
+

paystack_webhooks/idempotency.py

@@ -0,0 +1,66 @@
+"""Deduplication, because both providers retry on any non-2xx.
+
+The store is deliberately tiny and in-memory: it is correct for one process and
+honest about it. A multi-instance deployment needs a shared store (Redis, a table
+with a unique key), which is why the protocol exists rather than a hard-coded dict.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Callable, Dict, Protocol
+
+
+class Store(Protocol):
+    """Anything that can answer 'have I seen this key before?' atomically."""
+
+    def seen(self, key: str) -> bool:
+        """Record the key and return True if it was already present."""
+        ...
+
+
+class MemoryStore:
+    """Thread-safe, TTL-bounded, capped. Single process only.
+
+    ``seen`` both checks and records in one locked operation, so two concurrent
+    deliveries of the same event cannot both be told it is new. A check-then-record
+    API would race, and that race is a double charge.
+    """
+
+    def __init__(self, ttl_seconds: int = 86400, max_entries: int = 10_000,
+                 clock: Callable[[], float] = time.monotonic) -> None:
+        if ttl_seconds <= 0:
+            raise ValueError("ttl_seconds must be positive")
+        if max_entries <= 0:
+            raise ValueError("max_entries must be positive")
+        self._ttl = float(ttl_seconds)
+        self._max = int(max_entries)
+        self._clock = clock
+        self._lock = threading.Lock()
+        self._seen: Dict[str, float] = {}
+
+    def seen(self, key: str) -> bool:
+        if not key:
+            raise ValueError("an idempotency key is required")
+        now = self._clock()
+        with self._lock:
+            self._evict(now)
+            if key in self._seen:
+                return True
+            self._seen[key] = now
+            return False
+
+    def __len__(self) -> int:
+        with self._lock:
+            self._evict(self._clock())
+            return len(self._seen)
+
+    def _evict(self, now: float) -> None:
+        expired = [k for k, at in self._seen.items() if now - at > self._ttl]
+        for key in expired:
+            del self._seen[key]
+        if len(self._seen) > self._max:
+            overflow = len(self._seen) - self._max
+            for key in sorted(self._seen, key=lambda k: self._seen[k])[:overflow]:
+                del self._seen[key]

paystack_webhooks/paystack.py

@@ -0,0 +1,72 @@
+"""Paystack webhooks.
+
+Paystack signs the **raw request body** with HMAC-SHA512 using your secret key and
+sends the hex digest in ``x-paystack-signature``. Two consequences that trip up
+most integrations:
+
+* You must verify the bytes that arrived, before any JSON parsing. Re-encoding a
+  parsed dict changes whitespace and key order, so the digest no longer matches.
+* The signature covers the body only. Paystack sends no signed timestamp, so a
+  captured delivery stays valid forever. Freshness cannot be proven cryptographically;
+  deduplicate on ``event_id`` and treat that as your replay defence.
+"""
+
+from __future__ import annotations
+
+from typing import Mapping, Optional
+
+from .errors import MalformedPayload, RawBodyRequired, SignatureError
+from .event import Event, build_event, header, load_json
+from .idempotency import Store
+from .signature import constant_time_equals, hmac_sha512_hex
+
+SIGNATURE_HEADER = "x-paystack-signature"
+PROVIDER = "paystack"
+
+
+class PaystackWebhook:
+    """Verify and decode Paystack webhook deliveries."""
+
+    def __init__(self, secret_key: str, *, store: Optional[Store] = None) -> None:
+        if not secret_key or not str(secret_key).strip():
+            raise ValueError("secret_key is required: pass your Paystack secret key")
+        self._secret = str(secret_key).strip()
+        self._store = store
+
+    def expected_signature(self, body: bytes) -> str:
+        """The digest Paystack should have sent for these exact bytes."""
+        return hmac_sha512_hex(self._secret, body)
+
+    def parse(self, body: bytes, headers: Mapping[str, str]) -> Event:
+        """Verify the signature and return the event, or raise."""
+        if isinstance(body, str):
+            raise RawBodyRequired(
+                "body arrived as str, which cannot be verified: re-encoding changes the "
+                "digest. Pass the raw bytes instead (request.body(), request.get_data()).")
+        if isinstance(body, (bytearray, memoryview)):
+            body = bytes(body)
+        if not isinstance(body, bytes):
+            raise RawBodyRequired(
+                "body must be raw bytes; pass request.body() before parsing JSON")
+        provided = header(headers, SIGNATURE_HEADER)
+        if not constant_time_equals(self.expected_signature(body), provided):
+            raise SignatureError(
+                "x-paystack-signature did not match the body for the configured secret")
+        try:
+            payload = load_json(body)
+        except ValueError as exc:
+            raise MalformedPayload(str(exc)) from exc
+        if not str(payload.get("event") or payload.get("event_type") or "").strip():
+            raise MalformedPayload("payload has no 'event' field")
+        return build_event(PROVIDER, payload, body, headers or {})
+
+    def process(self, body: bytes, headers: Mapping[str, str],
+                *, store: Optional[Store] = None) -> Optional[Event]:
+        """Verify, then return the event once. A repeat delivery returns ``None``."""
+        event = self.parse(body, headers)
+        target = store if store is not None else self._store
+        if target is not None and target.seen(event.event_id):
+            return None
+        return event
+
+

paystack_webhooks/signature.py

@@ -0,0 +1,28 @@
+"""HMAC helpers. Constant-time comparisons, no shortcuts."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+
+def hmac_sha512_hex(secret: str, body: bytes) -> str:
+    """Paystack signs the raw body with HMAC-SHA512 and sends the hex digest."""
+    return hmac.new(secret.encode("utf-8"), body, hashlib.sha512).hexdigest()
+
+
+def hmac_sha256_hex(secret: str, body: bytes) -> str:
+    """Provided for providers that use SHA-256; not used by Paystack."""
+    return hmac.new(secret.encode("utf-8"), body, hashlib.sha256).hexdigest()
+
+
+def constant_time_equals(expected: str, provided: str) -> bool:
+    """Compare two strings without leaking length or content through timing.
+
+    Both operands are normalised to bytes first: ``compare_digest`` rejects ``str``
+    arguments outside the ASCII range, which would otherwise raise on a crafted
+    header instead of returning False.
+    """
+    if not expected or not provided:
+        return False
+    return hmac.compare_digest(expected.encode("utf-8"), provided.strip().encode("utf-8"))