motia/bitbylaw/steps/vmh

VMH Webhook & Sync Steps

📚 Vollständige Sync-Dokumentation: ../../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:

[
  {
    "id": "entity-123",
    "name": "John Doe",
    "createdAt": "2025-01-20T10:00:00Z"
  }
]

Response:

{
  "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

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

# 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

# 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

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