motia/bitbylaw/steps/vmh

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:

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

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:

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

# 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