From fab2f7f701fb2173bd08aee72e7b8cab4f7762c2 Mon Sep 17 00:00:00 2001
From: claudi <claudius.hansch@hoerl-im.de>
Date: Mon, 23 Feb 2026 10:26:02 +0100
Subject: [PATCH] doc: Add webhook handling for Elytra Event API with
 authentication and event routing to read me

---
 README.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)

diff --git a/README.md b/README.md
index c6328bb..3579e89 100644
--- a/README.md
+++ b/README.md
@@ -165,6 +165,69 @@ See [elytra_client/rest_api/README.md](elytra_client/rest_api/README.md) for com
 - Error handling
 - Common usage scenarios
 
+## Webhooks (Elytra Event API)
+
+The package includes a subpackage for handling CloudEvents-based webhooks from the Elytra PIM Event API.
+
+### Quick Start
+
+```python
+from elytra_client.webhooks import CloudEvent, parse_webhook_payload
+
+# Parse an incoming webhook payload
+event = parse_webhook_payload(request.json())
+print(f"Event type: {event.eventtype}")
+print(f"Object ID: {event.get_object_id()}")
+```
+
+### With Authentication Validation
+
+```python
+from elytra_client.webhooks import WebhookValidator, BasicAuth
+
+auth = BasicAuth(username="user", password="pass")
+validator = WebhookValidator(auth_type="basic", auth=auth)
+
+event = validator.validate_and_parse(
+    payload=request.json(),
+    headers=dict(request.headers)
+)
+```
+
+### Features
+
+- 📨 **CloudEvents Support**: Strongly-typed Pydantic models following the CNCF CloudEvents v1.0 spec
+- 🔐 **Flexible Authentication**: Basic, Bearer token, and API Key authentication
+- 🔀 **Event Routing**: `SimpleWebhookEventDispatcher` to route events by type and operation to dedicated handlers
+- 🔁 **Retry Logic**: Exponential backoff retry policies for reliable webhook delivery
+- 🌐 **Framework Integration**: Ready-to-use examples for Flask and FastAPI
+
+### Authentication Methods
+
+```python
+# Basic authentication
+auth = BasicAuth(username="admin", password="secret")
+
+# Bearer token
+auth = BearerAuth(token="eyJhbGciOiJIUzI1NiIs...")
+
+# API Key (custom header)
+auth = APIKeyAuth(api_key="sk_live_secret123", header_name="X-API-Key")
+```
+
+### Event Types and Operations
+
+Events carry an `EventType` (e.g., `PRODUCT`, `PRODUCT_GROUP`, `PRODUCT_ATTRIBUTE_VALUE`) and an `Operation` (`ADD`, `MODIFY`, `REMOVE`, `LINK`, `UNLINK`).
+
+### Documentation
+
+See [elytra_client/webhooks/README.md](elytra_client/webhooks/README.md) for comprehensive webhook documentation, including:
+- Complete API reference
+- Authentication details
+- Event routing and dispatching
+- Retry logic configuration
+- Flask and FastAPI integration examples
+
 ## API Methods
 
 All methods return Pydantic models with full type validation and IDE autocompletion support.