webhookd-sdk 0.1.0__tar.gz

webhookd_sdk-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.env
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Node / TypeScript
+node_modules/
+typescript/dist/
+*.tsbuildinfo
+coverage/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

webhookd_sdk-0.1.0/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.

webhookd_sdk-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,54 @@
+# 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/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "webhookd-sdk"
+version = "0.1.0"
+description = "Official Python SDK for NimbusNexus Webhooks — publish events + verify webhook signatures."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "NimbusNexus" }]
+keywords = ["webhook", "webhooks", "hmac", "signature", "verify", "nimbusnexus", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://github.com/NimbusNexus/Webhooks-sdks/tree/develop/python#readme"
+Repository = "https://github.com/NimbusNexus/Webhooks-sdks"
+Issues = "https://github.com/NimbusNexus/Webhooks-sdks/issues"
+
+[project.optional-dependencies]
+dev = ["pytest", "ruff", "mypy"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["webhookd_sdk"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+pythonpath = ["."]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "B", "UP"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_unused_ignores = true
+ignore_missing_imports = true

webhookd_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,86 @@
+"""Publish client — exercised against an httpx MockTransport (no network)."""
+
+from __future__ import annotations
+
+import json
+
+import httpx
+import pytest
+
+from webhookd_sdk import Client, WebhookdAPIError
+
+_OK = {
+    "id": "evt_db",
+    "event_uid": "u1",
+    "event_type": "order.created",
+    "application": "default",
+    "environment": "prod",
+    "deliveries_created": 2,
+    "source": None,
+}
+
+
+def _client(handler, **kw) -> Client:
+    return Client("https://wh.example.com", "whsk_x", transport=httpx.MockTransport(handler), **kw)
+
+
+def test_publish_success_and_request_shape():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url.path == "/v1/events"
+        assert request.headers["Authorization"] == "Bearer whsk_x"
+        body = json.loads(request.content)
+        assert body["event_type"] == "order.created"
+        assert body["payload"] == {"id": 1} and body["environment"] == "prod"
+        return httpx.Response(201, json=_OK)
+
+    with _client(handler) as c:
+        ev = c.publish("order.created", {"id": 1})
+    assert ev.event_uid == "u1" and ev.deliveries_created == 2
+
+
+def test_idempotency_key_header():
+    seen: dict[str, str | None] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["idem"] = request.headers.get("Idempotency-Key")
+        return httpx.Response(201, json=_OK)
+
+    with _client(handler) as c:
+        c.publish("order.created", {"id": 1}, idempotency_key="order-123")
+    assert seen["idem"] == "order-123"
+
+
+def test_api_error_carries_envelope():
+    def handler(_request: httpx.Request) -> httpx.Response:
+        return httpx.Response(422, json={"error": {"code": "validation_error", "message": "bad"}})
+
+    with _client(handler) as c, pytest.raises(WebhookdAPIError) as ei:
+        c.publish("order.created", {})
+    assert ei.value.status_code == 422 and ei.value.code == "validation_error"
+    assert ei.value.message == "bad"
+
+
+def test_retries_on_503_then_succeeds():
+    calls = {"n": 0}
+
+    def handler(_request: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        if calls["n"] == 1:
+            return httpx.Response(503, json={"error": {"code": "unavailable", "message": "x"}})
+        return httpx.Response(201, json=_OK)
+
+    with _client(handler, max_retries=2) as c:
+        ev = c.publish("order.created", {})
+    assert calls["n"] == 2 and ev.event_uid == "u1"
+
+
+def test_does_not_retry_4xx():
+    calls = {"n": 0}
+
+    def handler(_request: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        return httpx.Response(404, json={"error": {"code": "not_found", "message": "no app"}})
+
+    with _client(handler, max_retries=2) as c, pytest.raises(WebhookdAPIError):
+        c.publish("order.created", {})
+    assert calls["n"] == 1  # a 404 is terminal — not retried

webhookd_sdk-0.1.0/tests/test_e2e_webhookd.py

@@ -0,0 +1,102 @@
+"""End-to-end: the SDK ``Client`` publishing against a REAL in-process webhookd, driven through
+FastAPI's ``TestClient`` ASGI bridge (no network, no server). This goes beyond the mocked-transport
+unit tests — it proves the client authenticates and shapes ``POST /v1/events`` correctly and parses
+webhookd's real ``EventOut`` (incl. fan-out counting + idempotent replay).
+
+webhookd is NOT a PyPI package, so this is SKIPPED unless it's importable — it runs locally (or in a
+combined lane where webhookd is on the path), not in the pure-SDK CI. The signature *verify* path is
+covered independently by the server-generated vector fixture (``test_vectors.py``) + the live
+delivery-core parity check (``test_signature.py``).
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+import tempfile
+
+import httpx
+import pytest
+
+# webhookd reads its Settings (and builds its engine) at import time, so configure BEFORE importing
+# it — mirrors webhookd's own conftest. A file-backed sqlite (not :memory:) so every connection sees
+# the same DB; a 32-byte test KEK so endpoint-secret envelope encryption works offline.
+_DB = os.path.join(tempfile.gettempdir(), "sdk_e2e_webhookd.db")
+os.environ.setdefault("WEBHOOKD_DATABASE_URL", f"sqlite:///{_DB}")
+os.environ.setdefault("WEBHOOKD_SERVICE_TOKEN", "e2e-token")
+os.environ.setdefault(
+    "WEBHOOKD_KEK", base64.urlsafe_b64encode(b"webhookd-e2e-kek-0123456789abcde").decode()
+)
+
+pytest.importorskip(
+    "webhookd", reason="webhookd not installed — e2e runs only where it's available"
+)
+
+import webhookd.models  # noqa: E402,F401 — register tables on Base.metadata
+from fastapi.testclient import TestClient  # noqa: E402
+from webhookd import service  # noqa: E402
+from webhookd.app import app  # noqa: E402
+from webhookd.db import Base, SessionLocal, engine  # noqa: E402
+
+from webhookd_sdk import Client  # noqa: E402
+
+BASE = "http://testserver"  # httpx's ASGI convention
+TOKEN = os.environ["WEBHOOKD_SERVICE_TOKEN"]
+AUTH = {"Authorization": f"Bearer {TOKEN}"}
+
+
+@pytest.fixture
+def transport():
+    """A fresh-DB sync transport bridged to the real webhookd ASGI app. Drop/create + seed the
+    default tenant per test (TestClient's lifespan also seeds idempotently), then hand the SDK its
+    own httpx transport so the SDK's sync Client can drive the real app in-process."""
+    Base.metadata.drop_all(bind=engine)
+    Base.metadata.create_all(bind=engine)
+    with SessionLocal() as s:
+        service.ensure_seed(s)
+    with TestClient(app) as tc:  # keeps the ASGI bridge (portal) alive for the test body
+        yield tc._transport
+
+
+def _register_endpoint(transport, event_type: str) -> None:
+    """Register an endpoint subscribed EXACTLY to `event_type` via the real API, so each test's
+    fan-out count is independent of any other endpoints in the DB."""
+    with httpx.Client(base_url=BASE, transport=transport, headers=AUTH) as raw:
+        r = raw.post(
+            "/v1/endpoints",
+            json={
+                "url": "https://sub.example.com/hook",
+                "environment": "prod",
+                "subscriptions": [{"match_kind": "exact", "pattern": event_type}],
+            },
+        )
+        assert r.status_code == 201, r.text
+
+
+def test_sdk_publishes_against_real_webhookd(transport):
+    """The SDK publishes a real event; webhookd persists it and returns a real EventOut."""
+    with Client(BASE, TOKEN, transport=transport) as c:
+        ev = c.publish("order.created", {"id": 1})
+    assert ev.event_uid and ev.event_type == "order.created"
+    assert ev.application == "default" and ev.environment == "prod"
+
+
+def test_sdk_publish_fans_out_to_a_real_endpoint(transport):
+    """With a matching endpoint registered (via the real API — endpoint mgmt isn't the SDK's job),
+    the SDK publish fans out to exactly it."""
+    _register_endpoint(transport, "e2e.fanout")
+    with Client(BASE, TOKEN, transport=transport) as c:
+        ev = c.publish("e2e.fanout", {"id": 2})
+    assert ev.deliveries_created == 1
+
+
+def test_sdk_idempotent_publish_replays_not_refans(transport):
+    """A retried publish with the same Idempotency-Key returns the ORIGINAL event with no new
+    fan-out — the safety property the client's retries rely on."""
+    _register_endpoint(transport, "e2e.idem")
+    with Client(BASE, TOKEN, transport=transport) as c:
+        first = c.publish("e2e.idem", {"id": 3}, idempotency_key="dedupe-1")
+        again = c.publish("e2e.idem", {"id": 3}, idempotency_key="dedupe-1")
+    assert first.deliveries_created == 1
+    assert again.event_uid == first.event_uid
+    assert again.deliveries_created == 0  # replay: no re-fan-out

webhookd_sdk-0.1.0/tests/test_signature.py

@@ -0,0 +1,72 @@
+"""Signature verification — the crown jewel. Includes an independent known-answer vector and a
+byte-for-byte cross-check against the server's own signer (delivery-core) when it's importable."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+import pytest
+
+from webhookd_sdk import sign, verify
+
+SECRET = "whsec_test_value"
+BODY = b'{"data":{"id":1},"id":"evt_1","type":"order.created","version":"1"}'
+TS = 1_700_000_000
+
+
+def test_verify_known_vector():
+    # Independently construct the signed bytes (timestamp + "." + body) + HMAC — no SDK helper used.
+    expected = (
+        "sha256="
+        + hmac.new(SECRET.encode(), f"{TS}.".encode("ascii") + BODY, hashlib.sha256).hexdigest()
+    )
+    assert verify(SECRET, BODY, expected, timestamp=TS, now=TS)
+
+
+def test_sign_verify_roundtrip():
+    sig = sign(SECRET, BODY, TS)
+    assert sig.startswith("sha256=")
+    assert verify(SECRET, BODY, sig, timestamp=TS, now=TS)
+
+
+def test_signature_prefix_is_optional():
+    bare = sign(SECRET, BODY, TS).removeprefix("sha256=")
+    assert verify(SECRET, BODY, bare, timestamp=TS, now=TS)
+
+
+def test_rejects_tampered_body():
+    sig = sign(SECRET, BODY, TS)
+    assert not verify(SECRET, BODY + b" ", sig, timestamp=TS, now=TS)
+
+
+def test_rejects_wrong_secret():
+    sig = sign(SECRET, BODY, TS)
+    assert not verify("whsec_other", BODY, sig, timestamp=TS, now=TS)
+
+
+def test_rejects_stale_timestamp_replay():
+    sig = sign(SECRET, BODY, TS)
+    # 301s in the future of the signed timestamp -> outside the 300s window.
+    assert not verify(SECRET, BODY, sig, timestamp=TS, now=TS + 301)
+    assert verify(SECRET, BODY, sig, timestamp=TS, now=TS + 299)
+
+
+def test_accepts_str_timestamp_header():
+    # Subscribers pass the raw X-Webhook-Timestamp header (a string) straight through.
+    sig = sign(SECRET, BODY, TS)
+    assert verify(SECRET, BODY, sig, timestamp=str(TS), now=TS)
+
+
+def test_str_body_accepted():
+    sig = sign(SECRET, BODY.decode(), TS)
+    assert verify(SECRET, BODY.decode(), sig, timestamp=TS, now=TS)
+
+
+def test_matches_delivery_core_server_signer():
+    # The real proof: a signature produced by the SERVER's signer must verify with the SDK.
+    server_sign = pytest.importorskip("delivery_core.webhook_outbox").sign
+    server_sig = server_sign(SECRET, BODY, TS)
+    assert verify(SECRET, BODY, server_sig, timestamp=TS, now=TS)
+    # ... and our sign matches theirs exactly.
+    assert sign(SECRET, BODY, TS) == server_sig

webhookd_sdk-0.1.0/tests/test_vectors.py

@@ -0,0 +1,35 @@
+"""Cross-implementation signing-contract check. Every signature in fixtures/signature-vectors.json
+was produced by delivery-core — the SERVER's signer — so the SDK must reproduce AND verify each one.
+This pins the Python SDK to the exact wire contract without importing delivery_core — the guarantee
+holds even in a CI lane with no server installed (and the TS SDK checks the same file)."""
+
+from __future__ import annotations
+
+import json
+import pathlib
+
+import pytest
+
+from webhookd_sdk import sign, verify
+
+_FIXTURE = pathlib.Path(__file__).resolve().parents[2] / "fixtures" / "signature-vectors.json"
+VECTORS = json.loads(_FIXTURE.read_text(encoding="utf-8"))["vectors"]
+IDS = [v["name"] for v in VECTORS]
+
+
+@pytest.mark.parametrize("v", VECTORS, ids=IDS)
+def test_sdk_reproduces_server_signature(v):
+    """sign() must produce the EXACT bytes the server produced (a divergence in encoding / the
+    '<ts>.' join / hex casing fails here, not silently in production)."""
+    assert sign(v["secret"], v["body"], v["timestamp"]) == v["signature"]
+
+
+@pytest.mark.parametrize("v", VECTORS, ids=IDS)
+def test_sdk_verifies_server_signature(v):
+    ts = v["timestamp"]
+    assert verify(v["secret"], v["body"], v["signature"], timestamp=ts, now=ts)
+    # the bare hex (no 'sha256=' prefix) must also verify
+    bare = v["signature"].removeprefix("sha256=")
+    assert verify(v["secret"], v["body"], bare, timestamp=ts, now=ts)
+    # a one-byte tamper must be rejected
+    assert not verify(v["secret"], v["body"] + " ", v["signature"], timestamp=ts, now=ts)

webhookd_sdk-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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)