webhookd-sdk 0.1.0__py3-none-any.whl

webhookd_sdk/__init__.py

@@ -0,0 +1,24 @@
+"""webhookd-sdk — the official Python client for NimbusNexus Webhooks.
+
+- :func:`verify` — verify an incoming webhook's HMAC signature (for subscribers).
+- :class:`Client` — publish events to webhookd (for producers).
+"""
+
+from __future__ import annotations
+
+from webhookd_sdk.client import Client, Event
+from webhookd_sdk.errors import WebhookdAPIError, WebhookdError
+from webhookd_sdk.signature import DEFAULT_TOLERANCE_SECONDS, sign, verify
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Client",
+    "Event",
+    "WebhookdAPIError",
+    "WebhookdError",
+    "DEFAULT_TOLERANCE_SECONDS",
+    "sign",
+    "verify",
+    "__version__",
+]

webhookd_sdk/client.py

@@ -0,0 +1,147 @@
+"""Typed publish client for the webhookd API."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from webhookd_sdk.errors import WebhookdAPIError, WebhookdError
+
+_RETRY_STATUSES = frozenset({429, 500, 502, 503, 504})
+
+
+@dataclass
+class Event:
+    """The published event, as returned by ``POST /v1/events`` (webhookd's ``EventOut``)."""
+
+    id: str
+    event_uid: str
+    event_type: str
+    application: str
+    environment: str
+    deliveries_created: int
+    source: str | None = None
+
+    @classmethod
+    def _from_json(cls, d: dict[str, Any]) -> Event:
+        return cls(
+            id=d["id"],
+            event_uid=d["event_uid"],
+            event_type=d["event_type"],
+            application=d.get("application", "default"),
+            environment=d.get("environment", "prod"),
+            deliveries_created=d.get("deliveries_created", 0),
+            source=d.get("source"),
+        )
+
+
+class Client:
+    """Publish events to webhookd.
+
+    Authenticate with a per-tenant API key (``whsk_…``) or a service token::
+
+        with Client("https://webhooks.example.com", api_key="whsk_…") as wh:
+            event = wh.publish("order.created", {"id": 123}, idempotency_key="order-123")
+
+    Transient failures (connection errors, 429, 5xx) are retried with exponential backoff; a 429
+    honours its ``Retry-After`` header. Other 4xx raise :class:`WebhookdAPIError` carrying the
+    server's ``{error: {code, message}}`` envelope.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        timeout: float = 10.0,
+        max_retries: int = 2,
+        transport: httpx.BaseTransport | None = None,
+    ):
+        self._base = base_url.rstrip("/")
+        self._key = api_key
+        self._max_retries = max_retries
+        self._client = httpx.Client(timeout=timeout, transport=transport)
+
+    def publish(
+        self,
+        event_type: str,
+        payload: dict[str, Any],
+        *,
+        environment: str = "prod",
+        application: str = "default",
+        source: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> Event:
+        """Publish one event. ``idempotency_key`` makes the publish safe to retry (a replay returns
+        the original event without re-fanning-out)."""
+        body: dict[str, Any] = {
+            "event_type": event_type,
+            "payload": payload,
+            "environment": environment,
+            "application": application,
+        }
+        if source is not None:
+            body["source"] = source
+        headers = {"Authorization": f"Bearer {self._key}"}
+        if idempotency_key is not None:
+            headers["Idempotency-Key"] = idempotency_key
+        resp = self._post("/v1/events", body, headers)
+        return Event._from_json(resp.json())
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    # -- internals -------------------------------------------------------------
+    def _post(
+        self, path: str, json_body: dict[str, Any], headers: dict[str, str]
+    ) -> httpx.Response:
+        url = f"{self._base}{path}"
+        last_exc: Exception | None = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                resp = self._client.post(url, json=json_body, headers=headers)
+            except httpx.HTTPError as exc:
+                last_exc = exc
+                if attempt < self._max_retries:
+                    time.sleep(_backoff(attempt))
+                    continue
+                raise WebhookdError(f"request failed: {exc}") from exc
+
+            if resp.status_code in _RETRY_STATUSES and attempt < self._max_retries:
+                time.sleep(_retry_after(resp) or _backoff(attempt))
+                continue
+            if resp.status_code >= 400:
+                raise _api_error(resp)
+            return resp
+        raise WebhookdError(f"request failed after retries: {last_exc}")
+
+
+def _backoff(attempt: int) -> float:
+    return min(2.0, 0.2 * (2**attempt))
+
+
+def _retry_after(resp: httpx.Response) -> float | None:
+    raw = resp.headers.get("Retry-After")
+    if raw and raw.isdigit():
+        return float(raw)
+    return None
+
+
+def _api_error(resp: httpx.Response) -> WebhookdAPIError:
+    code, message = "error", resp.text
+    try:
+        err = resp.json().get("error") or {}
+        code = err.get("code", code)
+        message = err.get("message", message)
+    except Exception:  # noqa: BLE001 - a non-JSON error body falls back to the raw text
+        pass
+    return WebhookdAPIError(resp.status_code, code, message)

webhookd_sdk/errors.py

@@ -0,0 +1,21 @@
+"""SDK exceptions."""
+
+from __future__ import annotations
+
+
+class WebhookdError(Exception):
+    """Base class for all webhookd SDK errors (network failures, etc.)."""
+
+
+class WebhookdAPIError(WebhookdError):
+    """A non-2xx response from the webhookd API.
+
+    Carries the M5a error envelope: a stable machine ``code`` (e.g. ``"rate_limited"``,
+    ``"not_found"``, ``"validation_error"``) and a human ``message``, plus the HTTP ``status_code``.
+    """
+
+    def __init__(self, status_code: int, code: str, message: str):
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+        super().__init__(f"[{status_code} {code}] {message}")

webhookd_sdk/signature.py

@@ -0,0 +1,81 @@
+"""Verify webhookd webhook signatures.
+
+webhookd signs every delivery as ``HMAC_SHA256(secret, f"{timestamp}.".encode() + raw_body)`` (its
+default timestamped mode) and sends:
+
+- ``X-Webhook-Signature: sha256=<hex>``
+- ``X-Webhook-Timestamp: <unix-seconds>``
+
+A subscriber MUST verify the signature to prove the request genuinely came from webhookd and was not
+tampered with in transit. ``verify`` does it correctly: it rebuilds the signed bytes, enforces the
+replay window against the timestamp, and compares in constant time. This mirrors
+``delivery_core.webhook_outbox.{sign,verify}`` byte-for-byte.
+
+    from webhookd_sdk import verify
+
+    if not verify(secret, request.body, request.headers["X-Webhook-Signature"],
+                  timestamp=request.headers["X-Webhook-Timestamp"]):
+        return 400  # reject — forged, tampered, or replayed
+
+Pass the EXACT bytes you received as ``raw_body`` — do not re-serialize the JSON, or the signature
+won't match (webhookd signs the bytes on the wire).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+
+_PREFIX = "sha256="
+DEFAULT_TOLERANCE_SECONDS = 300
+
+
+def _as_bytes(value: str | bytes) -> bytes:
+    return value if isinstance(value, bytes) else value.encode("utf-8")
+
+
+def _signed_bytes(raw_body: bytes, timestamp: int | None) -> bytes:
+    if timestamp is None:
+        return raw_body
+    return f"{timestamp}.".encode("ascii") + raw_body
+
+
+def sign(secret: str | bytes, raw_body: str | bytes, timestamp: int | None = None) -> str:
+    """The ``sha256=<hex>`` signature webhookd would send for ``raw_body`` (+ optional timestamp).
+
+    Mainly useful for tests; subscribers call :func:`verify`.
+    """
+    digest = hmac.new(
+        _as_bytes(secret), _signed_bytes(_as_bytes(raw_body), timestamp), hashlib.sha256
+    ).hexdigest()
+    return f"{_PREFIX}{digest}"
+
+
+def verify(
+    secret: str | bytes,
+    raw_body: str | bytes,
+    signature: str,
+    *,
+    timestamp: int | str | None = None,
+    tolerance_seconds: int = DEFAULT_TOLERANCE_SECONDS,
+    now: int | None = None,
+) -> bool:
+    """Return ``True`` iff ``signature`` is a valid webhookd signature for ``raw_body``.
+
+    :param secret: the endpoint's signing secret (shown once at endpoint creation).
+    :param raw_body: the exact request body bytes received (do not re-serialize).
+    :param signature: the ``X-Webhook-Signature`` header (``sha256=…``; the prefix is optional).
+    :param timestamp: the ``X-Webhook-Timestamp`` header. When given, the signature is rejected if
+        it is older/newer than ``tolerance_seconds`` (replay protection) — always pass it.
+    :param tolerance_seconds: replay window; webhookd's default is 300s.
+    :param now: override the current unix time (for tests).
+    """
+    ts = int(timestamp) if timestamp is not None else None
+    if ts is not None:
+        current = int(time.time()) if now is None else now
+        if abs(current - ts) > tolerance_seconds:
+            return False
+    expected = sign(secret, raw_body, ts)
+    candidate = signature if signature.startswith(_PREFIX) else f"{_PREFIX}{signature}"
+    return hmac.compare_digest(expected, candidate)

webhookd_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: webhookd-sdk
+Version: 0.1.0
+Summary: Official Python SDK for NimbusNexus Webhooks — publish events + verify webhook signatures.
+Project-URL: Homepage, https://github.com/NimbusNexus/Webhooks-sdks/tree/develop/python#readme
+Project-URL: Repository, https://github.com/NimbusNexus/Webhooks-sdks
+Project-URL: Issues, https://github.com/NimbusNexus/Webhooks-sdks/issues
+Author: NimbusNexus
+License: MIT
+License-File: LICENSE
+Keywords: hmac,nimbusnexus,sdk,signature,verify,webhook,webhooks
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# webhookd-sdk (Python)
+
+Official Python SDK for **NimbusNexus Webhooks** — publish events, and verify the webhooks you receive.
+
+```sh
+pip install webhookd-sdk
+```
+
+## Verify an incoming webhook (subscribers)
+
+When webhookd delivers a webhook it signs the body with your endpoint's signing secret. **Always
+verify the signature** before trusting the payload — it proves the request really came from webhookd
+and wasn't tampered with or replayed.
+
+```python
+from webhookd_sdk import verify
+
+# In your webhook handler — pass the RAW request body bytes (do not re-serialize the JSON):
+ok = verify(
+    secret=ENDPOINT_SIGNING_SECRET,
+    raw_body=request.body,
+    signature=request.headers["X-Webhook-Signature"],
+    timestamp=request.headers["X-Webhook-Timestamp"],
+)
+if not ok:
+    return Response(status_code=400)  # forged, tampered, or outside the 300s replay window
+```
+
+## Publish an event (producers)
+
+```python
+from webhookd_sdk import Client, WebhookdAPIError
+
+with Client("https://webhooks.example.com", api_key="whsk_…") as wh:
+    try:
+        event = wh.publish(
+            "order.created",
+            {"order_id": "ord_123", "total": 4200},
+            idempotency_key="order-123",   # makes the publish safe to retry
+        )
+        print(event.event_uid, event.deliveries_created)
+    except WebhookdAPIError as e:
+        print(e.status_code, e.code, e.message)   # the stable {error:{code,message}} envelope
+```
+
+Transient failures (connection errors, `429`, `5xx`) are retried with backoff (a `429` honours
+`Retry-After`); other `4xx` raise `WebhookdAPIError`.
+
+## Develop
+
+```sh
+pip install -e '.[dev]'
+pytest && ruff check . && mypy webhookd_sdk
+```

webhookd_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+webhookd_sdk/__init__.py,sha256=6zonAUSFHB-fpqFWVsPPKY_W1lQezzc10rhsBGkUFIo,638
+webhookd_sdk/client.py,sha256=AEMbGwO9H1IWZQwyZ09hzHwj27IrxNUfLeSYGsqLDws,4748
+webhookd_sdk/errors.py,sha256=D64IwB9CsJwHKb4JhZkGmeDhnJzS9g0Bpkdy8-BITfE,680
+webhookd_sdk/signature.py,sha256=Nb9iSDIAj7mQzUAsTJNyNGZsVZ9U7wSmkQwOHR0wVYA,3171
+webhookd_sdk-0.1.0.dist-info/METADATA,sha256=B1oMecC_6qERBfncZXViqcKTB6Xk03ec2v2KNVcyuIU,2863
+webhookd_sdk-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+webhookd_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=hS9BbOZ6ifcDCGFnmJkTf-4i6DChPPi358uOIfLD4dE,1068
+webhookd_sdk-0.1.0.dist-info/RECORD,,

webhookd_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

webhookd_sdk-0.1.0.dist-info/licenses/LICENSE

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