Webhooks und MQTT

Bei jeder Änderung in vynst eine eigene URL, einen MQTT-Broker, Google Pub/Sub oder eine Datei per FTP und WebDAV benachrichtigen.

Webhooks melden Änderungen in vynst (inwendo ERP) an andere Systeme, sobald sie passieren. Home Assistant, Node-RED und n8n legen ihre Webhooks selbst an. Für alles andere legt ihr sie über die API oder in der Verwaltung an.

Webhook anlegen

curl --request POST https://eure-instanz.iw-erp.de/api/dw/webhook.json \
  --header 'x-iw-jwt-token: <TOKEN>' \
  --header 'content-type: application/json' \
  --data '{
    "data": {
      "name": "Neue Personen an unser CRM",
      "referenceClassName": "CRMPerson",
      "databaseAction": "create",
      "notificationType": "HTTP_POST",
      "notificationUrl": "https://example.org/hooks/vynst",
      "notificationClientToken": "ein-langes-geheimnis"
    }
  }'

Dafür braucht der Token das Recht Webhook (schreiben) und „Admin-Funktionen erlauben“.

Feld	Bedeutung
`referenceClassName`	Art der Datensätze, etwa `CRMPerson`, `CRMCompany`, `BaseBooking`, `Invoice`, `SmartLockLog`
`referenceIds`	optional nur bestimmte Datensätze
`databaseAction`	`create`, `update`, `delete`, bei Buchungen auch die Zeitpunkte `booking_pre_start`, `booking_start`, `booking_end`, `booking_post_end`
`notificationType`	Zustellweg, siehe unten
`notificationUrl`	Ziel; bei MQTT und Pub/Sub enthält der Pfad das Topic
`notificationClientId`, `notificationClientToken`	gehen als `X-IW-Client-Id` und `X-IW-Webhook-Token` mit
`notificationValuePath`	schickt aus `data` nur dieses eine Feld
`requestTimeout`	Zeitlimit in Sekunden

Zustellwege

`notificationType`	Ziel
`HTTP_POST`, `HTTP_PUT`, `HTTP_PATCH`	eure URL, nur `https`, höchstens zwei Weiterleitungen
`MQTT`	euer Broker: `mqtt://host:port/topic`
`OWN_MQTT`	der MQTT-Broker von vynst, Topic im Pfad
`PUB_SUB`	ein Google-Cloud-Pub/Sub-Topic
`FTP_FILE`, `WEBDAV_FILE`, `LOCAL_FILE`	eine Datei, deren Inhalt eine Vorlage erzeugt, zum Beispiel ein CSV für ein Altsystem

Was ankommt

POST /hooks/vynst HTTP/1.1
Content-Type: application/json
User-Agent: inwendo ERP/Webhook
X-IW-Client-Id: …
X-IW-Webhook-Token: ein-langes-geheimnis

{
  "iw_entity_class": "Inwendo\\CRMBundle\\Entity\\CRMPerson",
  "iw_entity_short_class": "CRMPerson",
  "iw_entity_id": "4711",
  "iw_action": "create",
  "iw_dt": 1760533200,
  "data": { "id": 4711, "first_name": "Anna", "last_name": "Beispiel" }
}

Prüft X-IW-Webhook-Token, bevor ihr etwas tut.
Webhooks werden im Hintergrund verschickt, die Reihenfolge ist nicht garantiert. Lest im Zweifel den aktuellen Stand per API nach.
Schloss-Protokolle und Check-ins tragen mit integration_ha_access_events_enabled zusätzlich eine kurze Zusammenfassung in webhook_data.

Keine Schleifen

Schreibt euer System nach einem Webhook wieder in vynst, setzt den Header X-IW-Trigger-Source (zum Beispiel X-IW-Trigger-Source: mein-crm). Webhooks, deren notificationClientId diesem Wert entspricht, werden für diese Änderung nicht ausgelöst. Node-RED und n8n machen das von selbst.

Fehlersuche

Schaltet für einen Webhook den Debug-Modus ein:

curl --request POST https://eure-instanz.iw-erp.de/api/dw/webhook/12/debug_mode.json \
  --header 'x-iw-jwt-token: <TOKEN>' \
  --header 'content-type: application/json' \
  --data '{"data": {"active": true, "seconds": 600}}'

Für höchstens 600 Sekunden schreibt vynst jede Ausführung mit Anfrage und Antwort ins Protokoll (GET /api/dw/webhook_log.json). Danach schaltet sich der Modus von selbst ab.

MQTT für Live-Daten

Jede Installation kann einen eigenen MQTT-Broker haben. vynst nutzt ihn für Live-Anzeigen (laufende Anrufe, Chat, Änderungen in Listen) und für Node-RED hinter einem Router.

Verbunden wird per WebSocket über TLS.
Die Anmeldung ist ein JWT, den vynst ausstellt. Er enthält, welche Topics der Client lesen und schreiben darf. Clients bekommen nie mehr Rechte als ihr Benutzer.
Topics beginnen mit der Adresse der Instanz. Bereiche wie logged-in/scope/call/live darf nur abonnieren, wer das passende Recht hat.

Für eigene Anbindungen ist ein Webhook vom Typ OWN_MQTT der einfachste Weg auf den Broker.

API

Die Endpunkte /api/dw/webhook und /api/dw/webhook_log stehen im Bereich Smart Home und Automationen.