# 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