Webhooks and MQTT

Notify your own URL, an MQTT broker, Google Pub/Sub or a file via FTP and WebDAV whenever something changes in vynst.

Webhooks report changes in vynst (inwendo ERP) to other systems as soon as they happen. Home Assistant, Node-RED and n8n create their webhooks themselves. For everything else, you create them through the API or in the admin area.

Creating a webhook

curl --request POST https://your-instance.iw-erp.de/api/dw/webhook.json \
  --header 'x-iw-jwt-token: <TOKEN>' \
  --header 'content-type: application/json' \
  --data '{
    "data": {
      "name": "New people for our CRM",
      "referenceClassName": "CRMPerson",
      "databaseAction": "create",
      "notificationType": "HTTP_POST",
      "notificationUrl": "https://example.org/hooks/vynst",
      "notificationClientToken": "a-long-secret"
    }
  }'

For this, the token needs the Webhook right (write) and “Allow admin functions”.

Field	Meaning
`referenceClassName`	type of records, for example `CRMPerson`, `CRMCompany`, `BaseBooking`, `Invoice`, `SmartLockLog`
`referenceIds`	optional, only certain records
`databaseAction`	`create`, `update`, `delete`; for bookings also the times `booking_pre_start`, `booking_start`, `booking_end`, `booking_post_end`
`notificationType`	delivery method, see below
`notificationUrl`	target; for MQTT and Pub/Sub, the path contains the topic
`notificationClientId`, `notificationClientToken`	sent as `X-IW-Client-Id` and `X-IW-Webhook-Token`
`notificationValuePath`	sends only this one field from `data`
`requestTimeout`	time limit in seconds

Delivery methods

`notificationType`	Target
`HTTP_POST`, `HTTP_PUT`, `HTTP_PATCH`	your URL, https only, at most two redirects
`MQTT`	your broker: `mqtt://host:port/topic`
`OWN_MQTT`	the MQTT broker of vynst, topic in the path
`PUB_SUB`	a Google Cloud Pub/Sub topic
`FTP_FILE`, `WEBDAV_FILE`, `LOCAL_FILE`	a file whose content a template generates, for example a CSV for a legacy system

What arrives

POST /hooks/vynst HTTP/1.1
Content-Type: application/json
User-Agent: inwendo ERP/Webhook
X-IW-Client-Id: …
X-IW-Webhook-Token: a-long-secret

{
  "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": "Example" }
}

Check X-IW-Webhook-Token before you do anything else.
Webhooks are sent in the background, and their order is not guaranteed. When in doubt, read the current state via the API.
If integration_ha_access_events_enabled is set, lock logs and check-ins also carry a short summary in webhook_data.

No loops

If your system writes back to vynst after a webhook, set the header X-IW-Trigger-Source (for example X-IW-Trigger-Source: my-crm). Webhooks whose notificationClientId matches this value are not triggered for that change. Node-RED and n8n do this automatically.

Troubleshooting

Turn on debug mode for a webhook:

curl --request POST https://your-instance.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}}'

For at most 600 seconds, vynst logs every execution with its request and response (GET /api/dw/webhook_log.json). Afterwards, the mode switches itself off.

MQTT for live data

Every installation can have its own MQTT broker. vynst uses it for live displays (ongoing calls, chat, changes in lists) and for Node-RED behind a router.

The connection uses WebSocket over TLS.
Sign-in is a JWT issued by vynst. It states which topics the client may read and write. Clients never get more rights than their user.
Topics begin with the address of the instance. Only someone with the matching right may subscribe to areas such as logged-in/scope/call/live.

For your own integrations, a webhook of type OWN_MQTT is the simplest way to reach the broker.

API

The endpoints /api/dw/webhook and /api/dw/webhook_log are listed under Smart home and automation.