Metadata-Version: 2.4
Name: webhookd-sdk
Version: 0.1.1
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
```
