webhook-co 0.1.0__tar.gz

webhook_co-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+dist/
+build/
+.coverage

webhook_co-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: webhook-co
+Version: 0.1.0
+Summary: The official Python SDK for the webhook.co API — a typed client with retries, cursor pagination, idempotency, and secret redaction.
+Project-URL: Homepage, https://webhook.co
+Project-URL: Repository, https://github.com/webhook-co/webhook
+Project-URL: Issues, https://github.com/webhook-co/webhook/issues
+Author: webhook.co
+License-Expression: Apache-2.0
+Keywords: api-client,sdk,standard-webhooks,webhook,webhook.co,webhooks
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: black==26.5.1; extra == 'dev'
+Requires-Dist: datamodel-code-generator==0.67.0; extra == 'dev'
+Requires-Dist: isort==8.0.1; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# webhook.co Python SDK
+
+The official Python SDK for the [webhook.co](https://webhook.co) API. A typed client with the hardening
+you'd otherwise hand-roll: bearer auth, bounded retries with jitter, cursor pagination, idempotency, and
+secret redaction — with pydantic v2 models generated from the same OpenAPI contract the API is built on.
+
+Python 3.10+. Built on `httpx`.
+
+## Install
+
+```sh
+pip install webhook-co
+```
+
+## Quickstart
+
+```python
+import os
+from webhook_co import WebhookClient
+
+client = WebhookClient(api_key=os.environ["WEBHOOK_API_KEY"])
+
+# Create an endpoint — the one-time ingest URL is returned once, so capture it now.
+endpoint = client.endpoints.create(name="orders-prod")
+print(endpoint.ingest_url)
+
+# List events for that endpoint (auto-paginates).
+for event in client.events.list(endpoint.id):
+    print(event.id, event.provider, event.verification_state)
+```
+
+The API key is a `whk_`-prefixed token from your dashboard. Keep it server-side — this SDK never prints
+it, but it's still a credential.
+
+Responses come back as validated pydantic models, so attributes are typed and snake_cased
+(`endpoint.org_id`, `endpoint.created_at`).
+
+## Pagination
+
+List methods return a `Paginator` you can iterate directly — it follows the cursor for you:
+
+```python
+for endpoint in client.endpoints.list(name="prod"):
+    print(endpoint.id)
+
+# Collect everything (careful with large result sets):
+failed = client.deliveries.list(status=["failed"]).collect()
+
+# One page at a time (e.g. to build your own UI):
+page = client.endpoints.list_page(limit=50)
+print(page.items, page.next_cursor)
+```
+
+## Errors
+
+Every failure is a `WebhookError` subclass, so you can narrow with `except` — no string matching:
+
+```python
+from webhook_co import (
+    WebhookRateLimitError,
+    WebhookNotFoundError,
+    WebhookAuthenticationError,
+)
+
+try:
+    client.endpoints.get(endpoint_id)
+except WebhookNotFoundError:
+    ...  # 404 — no such endpoint
+except WebhookRateLimitError as err:
+    print(f"retry after {err.retry_after_s}s")
+except WebhookAuthenticationError:
+    ...  # 401 — the key is invalid, expired, or revoked
+```
+
+Each error carries `code` (a stable capability-error string), `status` (the HTTP status), and
+`request_id` when the server sent one.
+
+## Retries & idempotency
+
+The client retries idempotent requests on transient failures (429/502/503/504 and network errors) with
+capped exponential backoff and jitter, honouring `Retry-After`. It **never** blind-retries a
+non-idempotent write — creating an endpoint, rotating a secret, or an un-keyed replay won't be sent twice
+by the SDK. Replays carry an idempotency key (auto-generated if you don't pass one), so those are safe:
+
+```python
+import uuid
+
+client.events.replay(
+    event.id,
+    target={"kind": "destination", "destinationId": destination_id},
+    idempotency_key=str(uuid.uuid4()),
+)
+```
+
+Tune the budget per client:
+
+```python
+client = WebhookClient(api_key, max_retries=4, timeout_s=15)  # defaults: 2 retries, 30s
+```
+
+## Payloads
+
+`events.get_payload` decodes the wire envelope and hands you the exact bytes (length-checked, so a
+truncated body raises rather than silently short-reading):
+
+```python
+payload = client.events.get_payload(event.id)
+print(payload.content_type, len(payload.body))  # payload.body is bytes
+```
+
+## Configuration
+
+| Argument       | Default                  | Notes                                                        |
+| -------------- | ------------------------ | ------------------------------------------------------------ |
+| `api_key`      | —                        | Required. A `whk_` API key.                                  |
+| `base_url`     | `https://api.webhook.co` | Must be https (loopback http allowed for self-host / dev).   |
+| `http_client`  | a new `httpx.Client`     | Pass your own for custom transports/proxies.                 |
+| `max_retries`  | `2`                      | Retries after the first attempt, idempotent requests only.   |
+| `timeout_s`    | `30`                     | Per-request timeout (seconds), per httpx connect/read/write phase. |
+| `refresh_auth` | —                        | Hook returning a rotated bearer on a 401 (OAuth flows).      |
+| `on_debug`     | —                        | Redacted, single-line diagnostics — never the raw key.       |
+
+Use it as a context manager to close the underlying connection pool:
+
+```python
+with WebhookClient(api_key) as client:
+    client.whoami()
+```
+
+## API surface
+
+`endpoints` (list · list_page · get · create · delete · rotate · `provider_secrets` add/list/revoke) ·
+`events` (list · list_page · get · get_payload · tail · replay) · `deliveries` (list · list_page · get) ·
+`replay_destinations` (create · list · delete · enable · set_ordered · rotate_signing_secret ·
+list_signing_secrets) · `subscriptions` (create · list · delete) · `audit.verify` · `whoami`.
+
+## License
+
+Apache-2.0

webhook_co-0.1.0/README.md

@@ -0,0 +1,139 @@
+# webhook.co Python SDK
+
+The official Python SDK for the [webhook.co](https://webhook.co) API. A typed client with the hardening
+you'd otherwise hand-roll: bearer auth, bounded retries with jitter, cursor pagination, idempotency, and
+secret redaction — with pydantic v2 models generated from the same OpenAPI contract the API is built on.
+
+Python 3.10+. Built on `httpx`.
+
+## Install
+
+```sh
+pip install webhook-co
+```
+
+## Quickstart
+
+```python
+import os
+from webhook_co import WebhookClient
+
+client = WebhookClient(api_key=os.environ["WEBHOOK_API_KEY"])
+
+# Create an endpoint — the one-time ingest URL is returned once, so capture it now.
+endpoint = client.endpoints.create(name="orders-prod")
+print(endpoint.ingest_url)
+
+# List events for that endpoint (auto-paginates).
+for event in client.events.list(endpoint.id):
+    print(event.id, event.provider, event.verification_state)
+```
+
+The API key is a `whk_`-prefixed token from your dashboard. Keep it server-side — this SDK never prints
+it, but it's still a credential.
+
+Responses come back as validated pydantic models, so attributes are typed and snake_cased
+(`endpoint.org_id`, `endpoint.created_at`).
+
+## Pagination
+
+List methods return a `Paginator` you can iterate directly — it follows the cursor for you:
+
+```python
+for endpoint in client.endpoints.list(name="prod"):
+    print(endpoint.id)
+
+# Collect everything (careful with large result sets):
+failed = client.deliveries.list(status=["failed"]).collect()
+
+# One page at a time (e.g. to build your own UI):
+page = client.endpoints.list_page(limit=50)
+print(page.items, page.next_cursor)
+```
+
+## Errors
+
+Every failure is a `WebhookError` subclass, so you can narrow with `except` — no string matching:
+
+```python
+from webhook_co import (
+    WebhookRateLimitError,
+    WebhookNotFoundError,
+    WebhookAuthenticationError,
+)
+
+try:
+    client.endpoints.get(endpoint_id)
+except WebhookNotFoundError:
+    ...  # 404 — no such endpoint
+except WebhookRateLimitError as err:
+    print(f"retry after {err.retry_after_s}s")
+except WebhookAuthenticationError:
+    ...  # 401 — the key is invalid, expired, or revoked
+```
+
+Each error carries `code` (a stable capability-error string), `status` (the HTTP status), and
+`request_id` when the server sent one.
+
+## Retries & idempotency
+
+The client retries idempotent requests on transient failures (429/502/503/504 and network errors) with
+capped exponential backoff and jitter, honouring `Retry-After`. It **never** blind-retries a
+non-idempotent write — creating an endpoint, rotating a secret, or an un-keyed replay won't be sent twice
+by the SDK. Replays carry an idempotency key (auto-generated if you don't pass one), so those are safe:
+
+```python
+import uuid
+
+client.events.replay(
+    event.id,
+    target={"kind": "destination", "destinationId": destination_id},
+    idempotency_key=str(uuid.uuid4()),
+)
+```
+
+Tune the budget per client:
+
+```python
+client = WebhookClient(api_key, max_retries=4, timeout_s=15)  # defaults: 2 retries, 30s
+```
+
+## Payloads
+
+`events.get_payload` decodes the wire envelope and hands you the exact bytes (length-checked, so a
+truncated body raises rather than silently short-reading):
+
+```python
+payload = client.events.get_payload(event.id)
+print(payload.content_type, len(payload.body))  # payload.body is bytes
+```
+
+## Configuration
+
+| Argument       | Default                  | Notes                                                        |
+| -------------- | ------------------------ | ------------------------------------------------------------ |
+| `api_key`      | —                        | Required. A `whk_` API key.                                  |
+| `base_url`     | `https://api.webhook.co` | Must be https (loopback http allowed for self-host / dev).   |
+| `http_client`  | a new `httpx.Client`     | Pass your own for custom transports/proxies.                 |
+| `max_retries`  | `2`                      | Retries after the first attempt, idempotent requests only.   |
+| `timeout_s`    | `30`                     | Per-request timeout (seconds), per httpx connect/read/write phase. |
+| `refresh_auth` | —                        | Hook returning a rotated bearer on a 401 (OAuth flows).      |
+| `on_debug`     | —                        | Redacted, single-line diagnostics — never the raw key.       |
+
+Use it as a context manager to close the underlying connection pool:
+
+```python
+with WebhookClient(api_key) as client:
+    client.whoami()
+```
+
+## API surface
+
+`endpoints` (list · list_page · get · create · delete · rotate · `provider_secrets` add/list/revoke) ·
+`events` (list · list_page · get · get_payload · tail · replay) · `deliveries` (list · list_page · get) ·
+`replay_destinations` (create · list · delete · enable · set_ordered · rotate_signing_secret ·
+list_signing_secrets) · `subscriptions` (create · list · delete) · `audit.verify` · `whoami`.
+
+## License
+
+Apache-2.0

webhook_co-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "webhook-co"
+version = "0.1.0"
+description = "The official Python SDK for the webhook.co API — a typed client with retries, cursor pagination, idempotency, and secret redaction."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "webhook.co" }]
+keywords = ["webhook", "webhooks", "sdk", "standard-webhooks", "webhook.co", "api-client"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27", "pydantic>=2.7"]
+
+[project.urls]
+Homepage = "https://webhook.co"
+Repository = "https://github.com/webhook-co/webhook"
+Issues = "https://github.com/webhook-co/webhook/issues"
+
+# Pinned exactly so the committed generated models (src/webhook_co/_generated/models.py) are byte-stable
+# across environments and the drift guard (tests/test_generated_drift.py) is reproducible in CI.
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "pytest-cov>=5",
+  "datamodel-code-generator==0.67.0",
+  "black==26.5.1",
+  "isort==8.0.1",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/webhook_co"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# Make the top-level `scripts` package importable by the generated-types drift test.
+pythonpath = ["."]
+
+[tool.coverage.run]
+source = ["webhook_co"]
+# The generated models carry no hand-written logic; they are drift-guarded, not coverage-guarded.
+omit = ["*/webhook_co/_generated/*"]
+
+[tool.coverage.report]
+exclude_also = ["if TYPE_CHECKING:", "raise NotImplementedError"]
+
+# The generated models are formatted by datamodel-code-generator's own black/isort pass; standalone
+# runs must not touch them or they'd diverge from a fresh generation (the drift test compares bytes).
+[tool.black]
+target-version = ["py310"]
+extend-exclude = "/_generated/"
+
+[tool.isort]
+profile = "black"
+extend_skip_glob = ["*/_generated/*"]

webhook_co-0.1.0/scripts/generate_models.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""Generate the SDK's pydantic v2 models from the golden OpenAPI document.
+
+The models are DERIVED from packages/openapi/src/openapi.json (itself drift-guarded against the Zod
+contract), so the SDK can never silently diverge from the wire shape. The output is committed and
+drift-tested (tests/test_generated_drift.py) exactly like the golden spec, using PINNED tool versions
+(see pyproject.toml [project.optional-dependencies].dev) so the bytes are reproducible in CI.
+
+Pipeline: run datamodel-code-generator, then collapse the scalar RootModel wrappers it emits for
+`anyOf: [constrained-scalar, null]` fields (so `delivery.status_code == 200` works instead of silently
+being False), then re-format with black. `render()` is the single source of truth used by both `main()`
+and the drift test, so the committed bytes are exactly reproducible.
+
+Regenerate:  python -m scripts.generate_models   (from sdks/python, with the dev extras installed)
+"""
+
+from __future__ import annotations
+
+import pathlib
+import re
+import subprocess
+import sys
+import tempfile
+
+import black
+
+HERE = pathlib.Path(__file__).resolve().parent
+PACKAGE_ROOT = HERE.parent
+SPEC = PACKAGE_ROOT.parent.parent / "packages" / "openapi" / "src" / "openapi.json"
+OUT = PACKAGE_ROOT / "src" / "webhook_co" / "_generated" / "models.py"
+
+# Flags chosen for a modern, stable pydantic v2 surface: PEP 604 unions (`X | None`), builtin generics
+# (`list`/`dict`), and `Annotated` field constraints, snake_case attributes with camelCase aliases,
+# `format: uuid` as plain str, forward-compatible `extra=ignore`, and OPEN enums (so an older SDK doesn't
+# crash on a new server-side enum value). Keep this list in lockstep with the drift test via `render()`.
+ARGS = [
+    "--input-file-type",
+    "openapi",
+    "--output-model-type",
+    "pydantic_v2.BaseModel",
+    "--target-python-version",
+    "3.10",
+    "--use-annotated",
+    "--use-standard-collections",
+    "--use-union-operator",
+    "--use-schema-description",
+    "--snake-case-field",
+    "--type-mappings",
+    "uuid=string",
+    "--ignore-enum-constraints",
+    "--extra-fields",
+    "ignore",
+    "--formatters",
+    "black",
+    "isort",
+    "--disable-timestamp",
+]
+
+# The pinned black target — matches the SDK's minimum Python and keeps the collapse re-format reproducible.
+_BLACK_MODE = black.Mode(target_versions={black.TargetVersion.PY310})
+
+_SIMPLE_BASES = {"int", "str", "float", "bool"}
+_ROOT_HEADER = re.compile(r"^class (\w+)\(RootModel\[(\w+)\]\):$")
+
+
+def build_argv(input_path: pathlib.Path, output_path: pathlib.Path) -> list[str]:
+    return [
+        sys.executable,
+        "-m",
+        "datamodel_code_generator",
+        "--input",
+        str(input_path),
+        "--output",
+        str(output_path),
+        *ARGS,
+    ]
+
+
+def _collapse_scalar_root_models(text: str) -> str:
+    """Inline `class X(RootModel[<scalar>])` wrappers to their base scalar.
+
+    datamodel-code-generator wraps a constrained scalar inside an `anyOf: [scalar, null]` in a named
+    RootModel (e.g. `StatusCode(RootModel[int])`), typing the field as `StatusCode | None`. That reads
+    wrong (`delivery.status_code == 200` is always False; `str(destination_id)` is `"root=..."`). Only
+    the SCALAR RootModels are collapsed; a union RootModel (e.g. `AuditVerifyResponse`) is left intact.
+    """
+    lines = text.split("\n")
+    kept: list[str] = []
+    mapping: dict[str, str] = {}
+    i = 0
+    while i < len(lines):
+        header = _ROOT_HEADER.match(lines[i])
+        if header and header.group(2) in _SIMPLE_BASES:
+            mapping[header.group(1)] = header.group(2)
+            # Drop the class block: its header + all following blank/indented body lines.
+            i += 1
+            while i < len(lines) and (
+                lines[i] == "" or lines[i].startswith((" ", "\t"))
+            ):
+                i += 1
+            continue
+        kept.append(lines[i])
+        i += 1
+    result = "\n".join(kept)
+    for name, base in mapping.items():
+        result = re.sub(rf"\b{name}\b", base, result)
+    return result
+
+
+def render(spec_path: pathlib.Path) -> str:
+    """The full generation pipeline (datamodel-codegen → collapse scalar RootModels → black). The single
+    source of truth for the committed file and the drift test.
+    """
+    with tempfile.TemporaryDirectory() as tmp:
+        raw_out = pathlib.Path(tmp) / "models.py"
+        subprocess.run(build_argv(spec_path, raw_out), check=True, capture_output=True)
+        raw = raw_out.read_text()
+    collapsed = _collapse_scalar_root_models(raw)
+    return black.format_str(collapsed, mode=_BLACK_MODE)
+
+
+def main() -> None:
+    OUT.parent.mkdir(parents=True, exist_ok=True)
+    OUT.write_text(render(SPEC))
+    print(f"✓ generated {OUT}")
+
+
+if __name__ == "__main__":
+    main()

webhook_co-0.1.0/src/webhook_co/__init__.py

@@ -0,0 +1,90 @@
+"""The official Python SDK for the webhook.co API.
+
+from webhook_co import WebhookClient
+
+client = WebhookClient(api_key="whk_...")
+for endpoint in client.endpoints.list():
+    print(endpoint.id, endpoint.name)
+"""
+
+from __future__ import annotations
+
+from ._errors import (
+    WebhookAPIError,
+    WebhookAuthenticationError,
+    WebhookConfigError,
+    WebhookConflictError,
+    WebhookConnectionError,
+    WebhookError,
+    WebhookInvalidRequestError,
+    WebhookNotFoundError,
+    WebhookPermissionError,
+    WebhookRateLimitError,
+    WebhookTargetUnreachableError,
+    WebhookUnexpectedResponseError,
+)
+from ._generated.models import (
+    AddedProviderSecret,
+    AuditVerifyResponse,
+    AuthContext,
+    CreatedEndpoint,
+    CreatedReplayDestination,
+    DeletedEndpoint,
+    Delivery,
+    DeliveryAttempt,
+    Endpoint,
+    Event,
+    EventsTailResponse,
+    EventSummary,
+    ProviderSecretSummary,
+    ReplayDestination,
+    ReplayDestinationDeleted,
+    RevokedProviderSecret,
+    RotatedSigningSecret,
+    SigningSecretMetadata,
+    Subscription,
+    SubscriptionDeleted,
+)
+from ._pagination import Page, Paginator
+from .client import EventPayload, WebhookClient
+
+__all__ = [
+    "WebhookClient",
+    "EventPayload",
+    "Page",
+    "Paginator",
+    # errors
+    "WebhookError",
+    "WebhookConfigError",
+    "WebhookConnectionError",
+    "WebhookAPIError",
+    "WebhookAuthenticationError",
+    "WebhookPermissionError",
+    "WebhookNotFoundError",
+    "WebhookInvalidRequestError",
+    "WebhookConflictError",
+    "WebhookRateLimitError",
+    "WebhookTargetUnreachableError",
+    "WebhookUnexpectedResponseError",
+    # models
+    "Endpoint",
+    "CreatedEndpoint",
+    "DeletedEndpoint",
+    "Event",
+    "EventSummary",
+    "EventsTailResponse",
+    "Delivery",
+    "DeliveryAttempt",
+    "ReplayDestination",
+    "CreatedReplayDestination",
+    "ReplayDestinationDeleted",
+    "RotatedSigningSecret",
+    "SigningSecretMetadata",
+    "Subscription",
+    "SubscriptionDeleted",
+    "AddedProviderSecret",
+    "ProviderSecretSummary",
+    "RevokedProviderSecret",
+    "AuditVerifyResponse",
+    "AuthContext",
+]

webhook_co-0.1.0/src/webhook_co/_config.py

@@ -0,0 +1,40 @@
+"""Client configuration resolution.
+
+The base URL is the destination for the bearer credential, so it MUST be https — plaintext http is
+rejected except for loopback (local dev / self-host) — otherwise a misconfiguration could downgrade the
+key to plaintext or redirect it to a hostile host. The URL must be a clean origin+path (no query/
+fragment); the normalised form is returned.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import urlsplit
+
+from ._errors import WebhookConfigError
+
+#: The canonical hosted API (mirrors the OpenAPI ``servers`` entry).
+DEFAULT_BASE_URL = "https://api.webhook.co"
+
+_LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+
+
+def resolve_base_url(raw: str | None) -> str:
+    """Validate + normalise a base URL (defaulting to the hosted API).
+
+    https-only except loopback http; no query/fragment; a trailing slash is stripped so
+    ``f"{base}/v1/…"`` concatenation is always well-formed.
+    """
+    value = raw or DEFAULT_BASE_URL
+    parts = urlsplit(value)
+    if not parts.scheme or not parts.netloc:
+        raise WebhookConfigError(f"invalid base URL: {value}")
+    loopback_http_ok = parts.scheme == "http" and parts.hostname in _LOOPBACK_HOSTS
+    if parts.scheme != "https" and not loopback_http_ok:
+        raise WebhookConfigError(
+            f"base URL must be https (got {parts.scheme}://): {value}"
+        )
+    if parts.query or parts.fragment:
+        raise WebhookConfigError(
+            f"base URL must not carry a query or fragment: {value}"
+        )
+    return f"{parts.scheme}://{parts.netloc}{parts.path}".rstrip("/")