Webhooks

Have the controller call an address of your own whenever a value changes

A webhook makes the controller call an address of your choice whenever a particular value changes. Your system neither has to keep a connection open nor poll; all it needs is an HTTP endpoint the controller can reach.

Webhooks are managed through the API only. Neither the app nor the configuration interface has a page for them. The calls need an account in the "admin" group, see Admin and regular user.

Adding a webhook

addWebHook adds a webhook and returns its ID:

Parameter	Meaning
type	component for a value of a component
cid	component, for example C5
property	value of the component, for example state
url	address the controller calls
enabled	optional, default true

Over HTTP this looks as follows:

curl -s -X POST http://<controller-ip>/api/v1/addWebHook \
  -H 'auth-username: <user>' -H 'auth-password: <password>' \
  -H 'Content-Type: application/json' \
  -d '{"type":"component","cid":"C5","property":"state","url":"http://192.168.0.20:8080/nomos-hook"}'

{"id":25}

If cid or property is missing, the controller answers {"errorCode":106,"errorText":"Parameter(s) error"}; an unknown type gives error code 112. The type join is meant for mRemote installations and is not described here.

The webhook survives restarts until you remove it.

The call

When the value changes, the controller calls the address with GET and appends four parameters:

GET /nomos-hook?id=25&cid=C5&property=state&content=1
User-Agent: <name of the controller>

Parameter	Content
id	ID of the webhook
cid	component
property	value of the component
content	new value, as the device reports it

content is the device's raw value, not the processed value from the API. A switching state therefore arrives as 1 or 0, not as true or false.

Your endpoint should answer with status 200. The controller waits at most 5 seconds and does not evaluate the answer. It does not repeat a failed call; it only notes it in its log. If your endpoint was unreachable for a while, fetch the current state over the API, for instance with getAllComponents.

A receiver to try it out, in Node.js:

require('http').createServer(function(req, res) {
    console.log(req.method, req.url, req.headers['user-agent']);
    res.end('ok');
}).listen(8080);

Managing webhooks

Call	Effect
getWebHooks	lists all webhooks with ID, type, target and state
disableWebHook	pauses a webhook ({"id":25}), it stays stored
enableWebHook	switches it back on
removeWebHook	removes it

curl -s -X POST http://<controller-ip>/api/v1/getWebHooks \
  -H 'auth-username: <user>' -H 'auth-password: <password>'

[{"id":25,"created":"2026-10-08T12:47:01.252Z","lastUpdate":"2026-10-08T12:47:01.252Z",
  "type":"component","url":"http://192.168.0.20:8080/nomos-hook","enabled":true,
  "cid":"C5","property":"state"}]

A webhook cannot be changed; remove it and add it again.

Security

• The call carries no authentication and no signature. Your endpoint cannot tell whether it really comes from the controller. Put a hard-to-guess path or parameter into the address, and make the endpoint reachable only from the controller's network.
• With https://, the controller verifies the target's certificate. A self-signed certificate makes the call fail.
• The address must be reachable from the controller. A target on the internet requires the controller to have internet access.