Aufteilung der README.md in modulare Dokumentation
- Haupt-README.md behält Übersicht und Links zu detaillierten READMEs - steps/advoware_proxy/README.md: Detaillierte Dokumentation der 4 Proxy-Steps - steps/vmh/README.md: Detaillierte Dokumentation der Webhook-Receiver und Sync-Steps - Verbesserte Navigation und modulare Dokumentationsstruktur
This commit is contained in:
root
194
bitbylaw/steps/vmh/README.md
Normal file
194
bitbylaw/steps/vmh/README.md
Normal file
@@ -0,0 +1,194 @@
|
||||
# VMH Webhook & Sync Steps
|
||||
|
||||
Dieser Ordner enthält die Webhook-Receiver für EspoCRM und den Event-basierten Synchronisations-Handler für Beteiligte-Entitäten.
|
||||
|
||||
## Übersicht
|
||||
|
||||
Die VMH-Steps implementieren eine vollständige Webhook-Pipeline:
|
||||
1. **Webhook Receiver** empfangen Events von EspoCRM
|
||||
2. **Redis Deduplication** verhindert Mehrfachverarbeitung
|
||||
3. **Event Emission** triggert die Synchronisation
|
||||
4. **Sync Handler** verarbeitet die Änderungen (aktuell Placeholder)
|
||||
|
||||
## Webhook Receiver Steps
|
||||
|
||||
### 1. Create Webhook (`webhook/beteiligte_create_api_step.py`)
|
||||
|
||||
**Zweck:** Empfängt Create-Webhooks von EspoCRM für neue Beteiligte-Entitäten.
|
||||
|
||||
**Konfiguration:**
|
||||
- **Type:** api
|
||||
- **Name:** VMH Webhook Beteiligte Create
|
||||
- **Path:** `/vmh/webhook/beteiligte/create`
|
||||
- **Method:** POST
|
||||
- **Flows:** vmh
|
||||
- **Emits:** `vmh.beteiligte.create`
|
||||
|
||||
**Funktionalität:**
|
||||
- Verarbeitet Batch-Payloads von EspoCRM
|
||||
- Extrahiert Entity-IDs aus dem Payload
|
||||
- Redis-basierte Deduplikation mit `vmh:beteiligte:create_pending`
|
||||
- Emittiert Events für neue Entities
|
||||
|
||||
**Payload Format:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "entity-123",
|
||||
"name": "John Doe",
|
||||
"createdAt": "2025-01-20T10:00:00Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "received",
|
||||
"action": "create",
|
||||
"new_ids_count": 1,
|
||||
"total_ids_in_batch": 1
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Update Webhook (`webhook/beteiligte_update_api_step.py`)
|
||||
|
||||
**Zweck:** Empfängt Update-Webhooks von EspoCRM für geänderte Beteiligte-Entitäten.
|
||||
|
||||
**Konfiguration:**
|
||||
- **Type:** api
|
||||
- **Name:** VMH Webhook Beteiligte Update
|
||||
- **Path:** `/vmh/webhook/beteiligte/update`
|
||||
- **Method:** POST
|
||||
- **Flows:** vmh
|
||||
- **Emits:** `vmh.beteiligte.update`
|
||||
|
||||
**Funktionalität:**
|
||||
- Ähnlich zum Create-Webhook
|
||||
- Verwendet `vmh:beteiligte:update_pending` für Deduplikation
|
||||
- Emittiert `vmh.beteiligte.update` Events
|
||||
|
||||
### 3. Delete Webhook (`webhook/beteiligte_delete_api_step.py`)
|
||||
|
||||
**Zweck:** Empfängt Delete-Webhooks von EspoCRM für gelöschte Beteiligte-Entitäten.
|
||||
|
||||
**Konfiguration:**
|
||||
- **Type:** api
|
||||
- **Name:** VMH Webhook Beteiligte Delete
|
||||
- **Path:** `/vmh/webhook/beteiligte/delete`
|
||||
- **Method:** POST
|
||||
- **Flows:** vmh
|
||||
- **Emits:** `vmh.beteiligte.delete`
|
||||
|
||||
**Funktionalität:**
|
||||
- Ähnlich zum Create-Webhook
|
||||
- Verwendet `vmh:beteiligte:delete_pending` für Deduplikation
|
||||
- Emittiert `vmh.beteiligte.delete` Events
|
||||
|
||||
## Sync Handler Step
|
||||
|
||||
### Event Sync Handler (`beteiligte_sync_event_step.py`)
|
||||
|
||||
**Zweck:** Zentraler Event-Handler für die Synchronisation von Beteiligte-Änderungen.
|
||||
|
||||
**Konfiguration:**
|
||||
- **Type:** event
|
||||
- **Name:** VMH Beteiligte Sync
|
||||
- **Subscribes:** `vmh.beteiligte.create`, `vmh.beteiligte.update`, `vmh.beteiligte.delete`
|
||||
- **Flows:** vmh
|
||||
- **Emits:** (none)
|
||||
|
||||
**Funktionalität:**
|
||||
- Empfängt Events von allen Webhook-Receivern
|
||||
- Aktuell Placeholder-Implementierung (nur Logging)
|
||||
- Entfernt verarbeitete IDs aus Redis-Pending-Queues
|
||||
- Bereit für Integration mit EspoCRM-API
|
||||
|
||||
**Event Data Format:**
|
||||
```json
|
||||
{
|
||||
"entity_id": "entity-123",
|
||||
"action": "create",
|
||||
"source": "webhook",
|
||||
"timestamp": "2025-01-20T10:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## Redis Deduplication
|
||||
|
||||
### Queue-Struktur
|
||||
- `vmh:beteiligte:create_pending` - IDs warten auf Create-Sync
|
||||
- `vmh:beteiligte:update_pending` - IDs warten auf Update-Sync
|
||||
- `vmh:beteiligte:delete_pending` - IDs warten auf Delete-Sync
|
||||
|
||||
### Deduplication Logic
|
||||
1. Sammle alle Entity-IDs aus Webhook-Payload
|
||||
2. Prüfe gegen bestehende Pending-Queue
|
||||
3. Nur neue IDs werden zur Queue hinzugefügt und Events emittiert
|
||||
4. Sync-Handler entfernt erfolgreich verarbeitete IDs
|
||||
|
||||
## Testing
|
||||
|
||||
### Webhook Simulation
|
||||
```bash
|
||||
# Create Webhook
|
||||
curl -X POST "http://localhost:3000/vmh/webhook/beteiligte/create" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '[{"id": "test-123", "name": "Test Entity"}]'
|
||||
|
||||
# Update Webhook
|
||||
curl -X POST "http://localhost:3000/vmh/webhook/beteiligte/update" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '[{"id": "test-123", "name": "Updated Entity"}]'
|
||||
|
||||
# Delete Webhook
|
||||
curl -X POST "http://localhost:3000/vmh/webhook/beteiligte/delete" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '[{"id": "test-123"}]'
|
||||
```
|
||||
|
||||
### Redis Monitoring
|
||||
```bash
|
||||
# Prüfe Pending-Queues
|
||||
redis-cli SMEMBERS vmh:beteiligte:create_pending
|
||||
redis-cli SMEMBERS vmh:beteiligte:update_pending
|
||||
redis-cli SMEMBERS vmh:beteiligte:delete_pending
|
||||
```
|
||||
|
||||
### Log Monitoring
|
||||
```bash
|
||||
motia logs | grep "VMH Webhook"
|
||||
motia logs | grep "PLATZHALTER"
|
||||
```
|
||||
|
||||
## Konfiguration
|
||||
|
||||
### Umgebungsvariablen
|
||||
- `REDIS_HOST` - Redis Host
|
||||
- `REDIS_PORT` - Redis Port
|
||||
- `REDIS_DB_ADVOWARE_CACHE` - Redis Database für Caching
|
||||
- `ESPOCRM_WEBHOOK_SECRET` - Webhook Secret für Authentifizierung
|
||||
|
||||
### Dependencies
|
||||
- `config.py` - Konfigurationsmanagement
|
||||
- `services/advoware.py` - Advoware API Client (für zukünftige Integration)
|
||||
|
||||
## Erweiterungen
|
||||
|
||||
### Geplante Features
|
||||
- Vollständige EspoCRM-API-Integration im Sync-Handler
|
||||
- Batch-Verarbeitung für große Datenmengen
|
||||
- Retry-Logic für fehlgeschlagene Syncs
|
||||
- Metriken und Monitoring
|
||||
- Webhook-Authentifizierung mit Secrets
|
||||
|
||||
### Error Handling
|
||||
- Detaillierte Fehlerlogs
|
||||
- Graceful Handling von Redis-Verbindungsfehlern
|
||||
- Payload-Validation
|
||||
- Dead-Letter-Queues für fehlgeschlagene Events
|
||||
|
||||
### Security
|
||||
- Webhook-Secret Validation
|
||||
- Input-Sanitization
|
||||
- Rate-Limiting für Webhook-Endpunkte
|
||||
Reference in New Issue
Block a user