Metadata-Version: 2.4
Name: pywebhook-lite
Version: 0.1.0
Summary: Simple webhook sender and receiver with HMAC signatures and retry logic
Author-email: Shahab Rashidian Dezfuly <mm4heidary@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/shahabRDZ/py-webhook
Project-URL: Repository, https://github.com/shahabRDZ/py-webhook
Project-URL: Issues, https://github.com/shahabRDZ/py-webhook/issues
Keywords: webhook,hmac,fastapi,http,api,signature
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT 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: Topic :: Internet :: WWW/HTTP
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24
Requires-Dist: fastapi>=0.100
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Dynamic: license-file

# py-webhook

[![PyPI version](https://badge.fury.io/py/py-webhook.svg)](https://pypi.org/project/py-webhook/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

Simple webhook sender and receiver for Python/FastAPI. Send webhooks with retry logic, receive with HMAC-SHA256 signature verification.

## Features

- **HMAC-SHA256 Signatures** -- every webhook is signed and verified
- **Retry Logic** -- configurable retries with exponential backoff
- **Async** -- built on `httpx` for non-blocking I/O
- **FastAPI Integration** -- drop-in `Depends()` for automatic verification
- **Lightweight** -- minimal dependencies, no magic

## Installation

```bash
pip install py-webhook
```

## Quick Start

### Sending Webhooks

```python
import asyncio
from pywebhook import WebhookSender

sender = WebhookSender(max_retries=3, timeout=10.0)

async def main():
    response = await sender.send(
        url="https://example.com/webhook",
        event="order.created",
        data={"order_id": 42, "total": 99.99},
        secret="your-shared-secret",
    )
    print(f"Delivered: {response.status_code}")

asyncio.run(main())
```

The sender automatically:
- Generates a `WebhookPayload` with a UUID, timestamp, event name, and your data
- Signs the JSON body with HMAC-SHA256
- Sends headers: `X-Webhook-Signature`, `X-Webhook-Event`, `X-Webhook-Id`
- Retries failed requests with exponential backoff

### Receiving Webhooks (FastAPI)

```python
from fastapi import Depends, FastAPI
from pywebhook import WebhookReceiver

app = FastAPI()
receiver = WebhookReceiver()

@app.post("/webhook")
async def handle_webhook(payload: dict = Depends(receiver.handler("your-shared-secret"))):
    print(f"Received event: {payload['event']}")
    print(f"Data: {payload['data']}")
    return {"status": "ok"}
```

The handler dependency automatically:
- Reads the raw request body
- Verifies the `X-Webhook-Signature` header against the shared secret
- Returns **401** if the signature is invalid
- Parses and returns the JSON payload

### Manual Verification

```python
from pywebhook import WebhookReceiver

receiver = WebhookReceiver()

body = b'{"event":"ping","data":{}}'
signature = "abc123..."
is_valid = receiver.verify(body, signature, secret="your-shared-secret")
```

### Payload Model

```python
from pywebhook import WebhookPayload

payload = WebhookPayload(event="user.signup", data={"user_id": 7})
print(payload.id)         # auto-generated UUID
print(payload.timestamp)  # auto-generated ISO 8601
print(payload.event)      # "user.signup"
print(payload.data)       # {"user_id": 7}
```

## Configuration

| Parameter | Default | Description |
|-----------|---------|-------------|
| `max_retries` | `3` | Number of delivery attempts |
| `timeout` | `10.0` | Request timeout in seconds |
| `backoff_base` | `1.0` | Base delay for exponential backoff (seconds) |

## License

MIT -- see [LICENSE](LICENSE) for details.
