motia/bitbylaw/steps/vmh/README.md

# VMH Webhook & Sync Steps

> **📚 Vollständige Sync-Dokumentation**: [../../docs/SYNC_OVERVIEW.md](../../docs/SYNC_OVERVIEW.md)

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 (✅ **Production Ready**)

## 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.

**Status:** ✅ **Production Ready** - Vollständig implementiert

**Konfiguration:**
- **Type:** event
- **Name:** VMH Beteiligte Sync
- **Subscribes:** 
  - `vmh.beteiligte.create` - Neue Entities
  - `vmh.beteiligte.update` - Änderungen
  - `vmh.beteiligte.delete` - Löschungen
  - `vmh.beteiligte.sync_check` - Cron-Checks (alle 15min)
- **Flows:** vmh

**Funktionalität:**
- ✅ Empfängt Events von allen Webhook-Receivern + Cron
- ✅ Redis Distributed Lock (verhindert Race Conditions)
- ✅ Beteiligte Sync (Stammdaten): rowId-basierte Change Detection
- ✅ Kommunikation Sync (Phone/Email/Fax): Hash-basierte Change Detection
- ✅ Konflikt-Handling: EspoCRM wins mit Notification
- ✅ Retry-Logic: Exponential Backoff (1min, 5min, 15min, 1h, 4h)
- ✅ Auto-Reset nach 24h bei permanently_failed

**Dokumentation:** Siehe [../../docs/SYNC_OVERVIEW.md](../../docs/SYNC_OVERVIEW.md)

## 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