Webhooks

Mit Webhooks können Ihre Systeme in Echtzeit auf Diagrammänderungen reagieren. Abonnieren Sie Lebenszyklus-Ereignisse, und EntityFlow sendet bei jedem Auslösen eine signierte Nutzlast per POST an Ihren Endpunkt.

Ereignisse

Ereignis	Ausgelöst, wenn
diagram.created	Ein Diagramm wird erstellt.
diagram.updated	Ein Diagramm wird gespeichert/aktualisiert.
diagram.deleted	Ein Diagramm wird gelöscht.

Ein Abonnement erstellen

POST /api/v1/webhooks mit einer Ziel-url und der Liste der events:

curl -X POST https://<your-host>/api/v1/webhooks \
  -H "Authorization: Bearer ef_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://example.com/hooks/entityflow",
        "events": ["diagram.created", "diagram.updated", "diagram.deleted"]
      }'

Die Antwort enthält ein Signaturgeheimnis — das nur einmal angezeigt wird. Bewahren Sie es sicher auf; Sie benötigen es, um Zustellungen zu verifizieren.

Zustellungen verifizieren

Jede Zustellung enthält Standard-Webhooks-Header:

Header	Zweck
webhook-id	Eindeutige Zustellungs-ID (für Idempotenz verwenden).
webhook-timestamp	Sendezeitpunkt (veraltete Zustellungen ablehnen).
webhook-signature	v1,<HMAC-SHA256 of the payload using your secret>.

Verifizieren Sie immer die Signatur, bevor Sie einer Zustellung vertrauen. Berechnen Sie den HMAC-SHA256 des Roh-Anfragetexts mit Ihrem Signaturgeheimnis neu und vergleichen Sie ihn (in konstanter Zeit) mit dem v1,...-Wert in webhook-signature.

tipp

Verwenden Sie die Standard Webhooks-Bibliotheken, um Signaturen sprachübergreifend korrekt zu verifizieren, anstatt eine eigene Lösung zu entwickeln.

HTTP-Ziele

https-Ziele sind immer zulässig. Klartext-http-Ziele sind als SSRF-Schutz standardmäßig blockiert. Selbst-Hoster können sie wie folgt zulassen:

export EF_WEBHOOK_ALLOW_HTTP=true

Weitere zugehörige Importer- und Netzwerkeinstellungen finden Sie in der Konfigurationsreferenz.