matterbridge-webhooks 1.0.2 → 1.1.0-edge.2

package/CHANGELOG.md

@@ -6,6 +6,61 @@ If you like this project and find it useful, please consider giving it a star on
 
 <a href="https://www.buymeacoffee.com/luligugithub"><img src="https://matterbridge.io/bmc-button.svg" alt="Buy me a coffee" width="120"></a>
 
+## [1.0.3-edge] - Not released
+
+### Added Webhook devices
+
+It allows to create a device based on webhooks.
+
+Features:
+
+- It is possible to choose the device type from the config.
+- It is possible to set the method with a prefix 'GET#' or 'POST# in the urls. Default if omitted is GET.
+- It is possible to use converters in the url.
+
+## Supported device types:
+
+| Device type    | Urls                                 |
+| -------------- | ------------------------------------ |
+| outlet         | on off                               |
+| onOffLight     | on off                               |
+| dimmerLight    | on off brightness                    |
+| colorTempLight | on off brightness colorTemp          |
+| extendedLight  | on off brightness colorTemp colorRgb |
+
+If there is interest, let me know and I will add all other device types.
+
+## Supported request converters:
+
+| Converter     | Return value        |
+| ------------- | ------------------- |
+| ${LEVEL}      | matter 1-254        |
+| ${LEVEL100}   | percentage 0-100    |
+| ${MIRED}      | colorTemp in mired  |
+| ${KELVIN}     | colorTemp in kelvin |
+| ${HUE}        | hue 0-360           |
+| ${SATURATION} | saturation 0-100    |
+| ${COLORX}     | colorX 0-1          |
+| ${COLORY}     | colorX 0-1          |
+
+## Supported cluster attributes:
+
+| Attributes    | Return value        |
+| ------------- | ------------------- |
+| ${level}      | matter 1-254        |
+| ${level100}   | percentage 0-100    |
+| ${mired}      | colorTemp in mired  |
+| ${kelvin}     | colorTemp in kelvin |
+| ${hue}        | hue 0-360           |
+| ${saturation} | saturation 0-100    |
+| ${colorX}     | colorX 0-1          |
+| ${colorY}     | colorX 0-1          |
+| ${red}        | red 0-255           |
+| ${gree}       | green 0-255         |
+| ${blue}       | blue 0-255          |
+
+<a href="https://www.buymeacoffee.com/luligugithub"><img src="https://matterbridge.io/bmc-button.svg" alt="Buy me a coffee" width="80"></a>
+
 ## [1.0.2] - 2025-12-12
 
 ### Changed

package/README.md

@@ -15,6 +15,8 @@
 
 ---
 
+# Webhooks
+
 This plugin allows you to expose any webhooks to Matter.
 
 Features:
@@ -24,11 +26,60 @@ Features:
 - It is possible to choose the method: GET or POST.
 - The webhook can be tested in the frontend.
 
-If you like this project and find it useful, please consider giving it a star on GitHub at https://github.com/Luligu/matterbridge-webhooks and sponsoring it.
+# Webhook devices
+
+It allows also to create a device based on webhooks.
+
+Features:
 
-<a href="https://www.buymeacoffee.com/luligugithub">
-  <img src="bmc-button.svg" alt="Buy me a coffee" width="120">
-</a>
+- It is possible to choose the device type from the config.
+- It is possible to set the method with a prefix 'GET#' or 'POST# in the urls. Default if omitted is GET.
+- It is possible to use converters in the url.
+
+## Supported device types:
+
+| Device type    | Urls                                 |
+| -------------- | ------------------------------------ |
+| outlet         | on off                               |
+| onOffLight     | on off                               |
+| dimmerLight    | on off brightness                    |
+| colorTempLight | on off brightness colorTemp          |
+| extendedLight  | on off brightness colorTemp colorRgb |
+
+If there is interest, let me know and I will add all other device types.
+
+## Supported request converters:
+
+| Converter     | Return value        |
+| ------------- | ------------------- |
+| ${LEVEL}      | matter 1-254        |
+| ${LEVEL100}   | percentage 0-100    |
+| ${MIRED}      | colorTemp in mired  |
+| ${KELVIN}     | colorTemp in kelvin |
+| ${HUE}        | hue 0-360           |
+| ${SATURATION} | saturation 0-100    |
+| ${COLORX}     | colorX 0-1          |
+| ${COLORY}     | colorX 0-1          |
+
+## Supported cluster attributes:
+
+| Attributes    | Return value        |
+| ------------- | ------------------- |
+| ${level}      | matter 1-254        |
+| ${level100}   | percentage 0-100    |
+| ${mired}      | colorTemp in mired  |
+| ${kelvin}     | colorTemp in kelvin |
+| ${hue}        | hue 0-360           |
+| ${saturation} | saturation 0-100    |
+| ${colorX}     | colorX 0-1          |
+| ${colorY}     | colorX 0-1          |
+| ${red}        | red 0-255           |
+| ${gree}       | green 0-255         |
+| ${blue}       | blue 0-255          |
+
+If you like this project and find it useful, please consider giving it a star on [GitHub](https://github.com/Luligu/matterbridge-webhooks) and sponsoring it.
+
+<a href="https://www.buymeacoffee.com/luligugithub"><img src="https://matterbridge.io/bmc-button.svg" alt="Buy me a coffee" width="120"></a>
 
 ## Prerequisites
 

package/dist/module.js

@@ -1,29 +1,28 @@
-import { bridgedNode, MatterbridgeDynamicPlatform, MatterbridgeEndpoint, onOffLight, onOffOutlet, onOffSwitch } from 'matterbridge';
-import { isValidObject } from 'matterbridge/utils';
+import { bridgedNode, colorTemperatureLight, dimmableLight, extendedColorLight, MatterbridgeDynamicPlatform, MatterbridgeEndpoint, onOffLight, onOffOutlet, onOffSwitch, } from 'matterbridge';
+import { hslColorToRgbColor, isValidNumber, isValidObject, isValidString, miredToKelvin, wait } from 'matterbridge/utils';
 import { fetch } from './fetch.js';
 export default function initializePlugin(matterbridge, log, config) {
     return new WebhooksPlatform(matterbridge, log, config);
 }
 export class WebhooksPlatform extends MatterbridgeDynamicPlatform {
-    webhooks;
-    bridgedDevices = new Map();
+    config;
     constructor(matterbridge, log, config) {
         super(matterbridge, log, config);
+        this.config = config;
         if (this.verifyMatterbridgeVersion === undefined || typeof this.verifyMatterbridgeVersion !== 'function' || !this.verifyMatterbridgeVersion('3.4.0')) {
             throw new Error(`This plugin requires Matterbridge version >= "3.4.0". Please update Matterbridge to the latest version in the frontend.`);
         }
         this.log.info('Initializing platform:', this.config.name);
-        this.webhooks = config.webhooks;
         this.log.info('Finished initializing platform:', this.config.name);
     }
     async onStart(reason) {
         this.log.info('onStart called with reason:', reason ?? 'none');
         await this.ready;
         await this.clearSelect();
-        let i = 0;
-        for (const webhookName in this.webhooks) {
-            this.log.debug(`Loading webhook ${++i} ${webhookName} with method ${this.webhooks[webhookName].method} and url ${this.webhooks[webhookName].httpUrl}`);
-            const webhook = this.webhooks[webhookName];
+        let i = 1;
+        for (const webhookName in this.config.webhooks) {
+            this.log.debug(`Loading webhook ${i} ${webhookName} with method ${this.config.webhooks[webhookName].method} and url ${this.config.webhooks[webhookName].httpUrl}`);
+            const webhook = this.config.webhooks[webhookName];
             this.setSelectDevice('webhook' + i, webhookName, undefined, 'hub');
             if (!this.validateDevice(['webhook' + i, webhookName], true))
                 continue;
@@ -35,6 +34,7 @@ export class WebhooksPlatform extends MatterbridgeDynamicPlatform {
                 .addCommandHandler('on', async () => {
                 this.log.info(`Webhook ${webhookName} triggered.`);
                 await device.setAttribute('onOff', 'onOff', false, device.log);
+                this.log.debug(`Fetching ${webhook.httpUrl} with ${webhook.method}...`);
                 fetch(webhook.httpUrl, webhook.method)
                     .then(() => this.log.notice(`Webhook ${webhookName} successful!`))
                     .catch((err) => {
@@ -42,16 +42,85 @@ export class WebhooksPlatform extends MatterbridgeDynamicPlatform {
                 });
             });
             await this.registerDevice(device);
-            this.bridgedDevices.set(webhookName, device);
+        }
+        i = 1;
+        for (const outletName in this.config.outlets) {
+            this.log.debug(`Loading outlet ${i} ${outletName}...`);
+            const webhook = this.config.outlets[outletName];
+            this.setSelectDevice('outlet' + i, outletName, undefined, 'hub');
+            if (!this.validateDevice(['outlet' + i, outletName], true))
+                continue;
+            this.log.info(`Registering outlet: ${outletName}...`);
+            const device = new MatterbridgeEndpoint([onOffOutlet, bridgedNode], { id: outletName }, this.config.debug)
+                .createDefaultBridgedDeviceBasicInformationClusterServer(outletName, 'outlet' + i++, this.matterbridge.aggregatorVendorId, 'Matterbridge', 'Matterbridge Webhook Outlet', 0, this.config.version)
+                .createOnOffClusterServer(false)
+                .addRequiredClusterServers()
+                .addCommandHandler('on', async (data) => {
+                this.parseUrl('outlet', outletName, 'on', webhook.onUrl, data);
+            })
+                .addCommandHandler('off', async (data) => {
+                this.parseUrl('outlet', outletName, 'off', webhook.offUrl, data);
+            });
+            await this.registerDevice(device);
+        }
+        i = 1;
+        for (const lightName in this.config.lights) {
+            this.log.debug(`Loading light ${i} ${lightName}...`);
+            const webhook = this.config.lights[lightName];
+            this.setSelectDevice('light' + i, lightName, undefined, 'hub');
+            if (!this.validateDevice(['light' + i, lightName], true))
+                continue;
+            this.log.info(`Registering light: ${lightName}...`);
+            let deviceType = onOffLight;
+            if (isValidString(webhook.brightnessUrl, 1))
+                deviceType = dimmableLight;
+            if (isValidString(webhook.colorTempUrl, 1))
+                deviceType = colorTemperatureLight;
+            if (isValidString(webhook.rgbUrl, 1))
+                deviceType = extendedColorLight;
+            const device = new MatterbridgeEndpoint([deviceType, bridgedNode], { id: lightName }, this.config.debug)
+                .createDefaultBridgedDeviceBasicInformationClusterServer(lightName, 'light' + i++, this.matterbridge.aggregatorVendorId, 'Matterbridge', 'Matterbridge Webhook Light', 0, this.config.version)
+                .createOnOffClusterServer(false)
+                .addRequiredClusterServers()
+                .addCommandHandler('on', async (data) => {
+                this.parseUrl('light', lightName, 'on', webhook.onUrl, data);
+            })
+                .addCommandHandler('off', async (data) => {
+                this.parseUrl('light', lightName, 'off', webhook.offUrl, data);
+            })
+                .addCommandHandler('moveToLevel', async (data) => {
+                this.parseUrl('light', lightName, 'moveToLevel', webhook.brightnessUrl, data);
+            })
+                .addCommandHandler('moveToLevelWithOnOff', async (data) => {
+                this.parseUrl('light', lightName, 'moveToLevelWithOnOff', webhook.brightnessUrl, data);
+            })
+                .addCommandHandler('moveToColorTemperature', async (data) => {
+                this.parseUrl('light', lightName, 'moveToColorTemperature', webhook.colorTempUrl, data);
+            })
+                .addCommandHandler('moveToHueAndSaturation', async (data) => {
+                this.parseUrl('light', lightName, 'moveToHueAndSaturation', webhook.rgbUrl, data);
+            })
+                .addCommandHandler('moveToHue', async (data) => {
+                this.parseUrl('light', lightName, 'moveToHue', webhook.rgbUrl, data);
+            })
+                .addCommandHandler('moveToSaturation', async (data) => {
+                this.parseUrl('light', lightName, 'moveToSaturation', webhook.rgbUrl, data);
+            })
+                .addCommandHandler('moveToColor', async (data) => {
+                this.parseUrl('light', lightName, 'moveToColor', webhook.rgbUrl, data);
+            });
+            await this.registerDevice(device);
         }
     }
     async onConfigure() {
         await super.onConfigure();
         this.log.info('onConfigure called');
-        this.bridgedDevices.forEach(async (device) => {
-            this.log.info(`Configuring device: ${device.deviceName}`);
-            await device.setAttribute('onOff', 'onOff', false, device.log);
-        });
+        for (const device of this.getDevices()) {
+            if (device.deviceName && device.deviceName in this.config.webhooks) {
+                this.log.info(`Configuring device: ${device.deviceName}`);
+                await device.setAttribute('onOff', 'onOff', false, device.log);
+            }
+        }
     }
     async onAction(action, value, id, formData) {
         this.log.info('onAction called with action:', action, 'and value:', value ?? 'none', 'and id:', id ?? 'none');
@@ -81,9 +150,9 @@ export class WebhooksPlatform extends MatterbridgeDynamicPlatform {
                 }
                 return;
             }
-            for (const webhookName in this.webhooks) {
-                if (Object.prototype.hasOwnProperty.call(this.webhooks, webhookName)) {
-                    const webhook = this.webhooks[webhookName];
+            for (const webhookName in this.config.webhooks) {
+                if (Object.prototype.hasOwnProperty.call(this.config.webhooks, webhookName)) {
+                    const webhook = this.config.webhooks[webhookName];
                     if (id?.includes(webhookName)) {
                         this.log.info(`Testing webhook ${webhookName} method ${webhook.method} url ${webhook.httpUrl}`);
                         fetch(webhook.httpUrl, webhook.method)
@@ -104,6 +173,96 @@ export class WebhooksPlatform extends MatterbridgeDynamicPlatform {
         this.log.info('onShutdown called with reason:', reason ?? 'none');
         if (this.config.unregisterOnShutdown === true)
             await this.unregisterAllDevices();
-        this.bridgedDevices.clear();
+    }
+    async parseUrl(deviceType, deviceName, command, url, data) {
+        this.log.info(`Webhook ${deviceType} ${deviceName} ${command} triggered.`);
+        let method = 'GET';
+        let parsedUrl = url;
+        if (url.startsWith('GET#')) {
+            method = 'GET';
+            parsedUrl = url.replace('GET#', '');
+        }
+        else if (url.startsWith('POST#')) {
+            method = 'POST';
+            parsedUrl = url.replace('POST#', '');
+        }
+        if (parsedUrl.includes('${LEVEL}') && isValidNumber(data.request.level)) {
+            parsedUrl = parsedUrl.replace('${LEVEL}', data.request.level.toString());
+        }
+        if (url.includes('${LEVEL100}') && isValidNumber(data.request.level)) {
+            parsedUrl = parsedUrl.replace('${LEVEL100}', Math.round((data.request.level / 254) * 100).toString());
+        }
+        if (parsedUrl.includes('${KELVIN}') && isValidNumber(data.request.colorTemperatureMireds)) {
+            parsedUrl = parsedUrl.replace('${KELVIN}', Math.round(miredToKelvin(data.request.colorTemperatureMireds)).toString());
+        }
+        if (parsedUrl.includes('${MIRED}') && isValidNumber(data.request.colorTemperatureMireds)) {
+            parsedUrl = parsedUrl.replace('${MIRED}', Math.round(data.request.colorTemperatureMireds).toString());
+        }
+        if (parsedUrl.includes('${COLORX}') && isValidNumber(data.request.colorX, 0, 65279)) {
+            parsedUrl = parsedUrl.replace('${COLORX}', this.roundTo(data.request.colorX / 65536, 4).toString());
+        }
+        if (parsedUrl.includes('${COLORY}') && isValidNumber(data.request.colorY, 0, 65279)) {
+            parsedUrl = parsedUrl.replace('${COLORY}', this.roundTo(data.request.colorY / 65536, 4).toString());
+        }
+        if (parsedUrl.includes('${HUE}') && isValidNumber(data.request.hue, 0, 254)) {
+            parsedUrl = parsedUrl.replace('${HUE}', Math.round((data.request.hue * 360) / 254).toString());
+        }
+        if (parsedUrl.includes('${SATURATION}') && isValidNumber(data.request.saturation, 0, 254)) {
+            parsedUrl = parsedUrl.replace('${SATURATION}', Math.round((data.request.saturation * 100) / 254).toString());
+        }
+        if ((parsedUrl.includes('${level}') || parsedUrl.includes('${level100}')) && isValidNumber(data.attributes.currentLevel, 1, 254)) {
+            await wait(100);
+            if (url.includes('${level}'))
+                parsedUrl = parsedUrl.replace('${level}', data.attributes.currentLevel.toString());
+            if (url.includes('${level100}'))
+                parsedUrl = parsedUrl.replace('${level100}', Math.round((data.attributes.currentLevel / 254) * 100).toString());
+        }
+        if ((parsedUrl.includes('${mired}') || parsedUrl.includes('${kelvin}')) &&
+            isValidNumber(data.attributes.colorTemperatureMireds, data.attributes.colorTempPhysicalMinMireds, data.attributes.colorTempPhysicalMaxMireds)) {
+            await wait(100);
+            const kelvin = miredToKelvin(data.attributes.colorTemperatureMireds);
+            this.log.debug(`Attribute colorTemperatureMireds is ${data.attributes.colorTemperatureMireds}, which is ${kelvin}K`);
+            if (url.includes('${mired}'))
+                parsedUrl = parsedUrl.replace('${mired}', data.attributes.colorTemperatureMireds.toString());
+            if (url.includes('${kelvin}'))
+                parsedUrl = parsedUrl.replace('${kelvin}', kelvin.toString());
+        }
+        if ((parsedUrl.includes('${hue}') || parsedUrl.includes('${saturation}') || parsedUrl.includes('${red}') || parsedUrl.includes('${green}') || parsedUrl.includes('${blue}')) &&
+            isValidNumber(data.attributes.currentHue, 0, 254) &&
+            isValidNumber(data.attributes.currentSaturation, 0, 254)) {
+            await wait(100);
+            const rgb = hslColorToRgbColor((data.attributes.currentHue * 360) / 254, (data.attributes.currentSaturation * 100) / 254, 50);
+            this.log.debug(`Converted hue ${data.attributes.currentHue} and saturation ${data.attributes.currentSaturation} to RGB r: ${rgb.r} g: ${rgb.g} b: ${rgb.b}`);
+            if (url.includes('${hue}'))
+                parsedUrl = parsedUrl.replace('${hue}', Math.round((data.attributes.currentHue * 360) / 254).toString());
+            if (url.includes('${saturation}'))
+                parsedUrl = parsedUrl.replace('${saturation}', Math.round((data.attributes.currentSaturation * 100) / 254).toString());
+            if (url.includes('${red}') && rgb)
+                parsedUrl = parsedUrl.replace('${red}', rgb.r.toString());
+            if (url.includes('${green}') && rgb)
+                parsedUrl = parsedUrl.replace('${green}', rgb.g.toString());
+            if (url.includes('${blue}') && rgb)
+                parsedUrl = parsedUrl.replace('${blue}', rgb.b.toString());
+        }
+        if ((parsedUrl.includes('${colorX}') || parsedUrl.includes('${colorY}')) &&
+            isValidNumber(data.attributes.currentX, 0, 65279) &&
+            isValidNumber(data.attributes.currentY, 0, 65279)) {
+            await wait(100);
+            if (url.includes('${colorX}'))
+                parsedUrl = parsedUrl.replace('${colorX}', this.roundTo(data.attributes.currentX / 65536, 4).toString());
+            if (url.includes('${colorY}'))
+                parsedUrl = parsedUrl.replace('${colorY}', this.roundTo(data.attributes.currentY / 65536, 4).toString());
+        }
+        this.log.debug(`Fetching ${parsedUrl} with ${method}...`);
+        fetch(parsedUrl, method)
+            .then(() => this.log.notice(`Webhook ${deviceType} ${deviceName} ${command} successful!`))
+            .catch((err) => {
+            this.log.error(`Webhook ${deviceType} ${deviceName} ${command} failed: ${err instanceof Error ? err.message : err}`);
+        });
+        return { method, url: parsedUrl };
+    }
+    roundTo(value, digits) {
+        const factor = Math.pow(10, digits);
+        return Math.round(value * factor) / factor;
     }
 }

package/matterbridge-webhooks.config.json

@@ -6,6 +6,8 @@
   "blackList": [],
   "deviceType": "Outlet",
   "webhooks": {},
+  "outlets": {},
+  "lights": {},
   "debug": false,
   "unregisterOnShutdown": false
 }

package/matterbridge-webhooks.schema.json

@@ -75,6 +75,65 @@
         }
       }
     },
+    "outlets": {
+      "description": "Define each outlet. Enter in the first field the name of the outlet (replace newKey with the name of the outlet) and in the right panel the urls (i.e. \"[GET|POST]#http://mydomain.com/api/device/on\").",
+      "type": "object",
+      "uniqueItems": true,
+      "additionalProperties": {
+        "type": "object",
+        "description": "Outlet parameters:",
+        "required": ["onUrl", "offUrl"],
+        "properties": {
+          "onUrl": {
+            "type": "string",
+            "title": "Outlet On URL",
+            "description": "URL to turn on the outlet."
+          },
+          "offUrl": {
+            "type": "string",
+            "title": "Outlet Off URL",
+            "description": "URL to turn off the outlet."
+          }
+        }
+      }
+    },
+    "lights": {
+      "description": "Define each light. Enter in the first field the name of the light (replace newKey with the name of the light) and in the right panel the urls (i.e. [GET|POST]#http://mydomain.com/api/device/on).",
+      "type": "object",
+      "uniqueItems": true,
+      "additionalProperties": {
+        "type": "object",
+        "description": "Light parameters:",
+        "required": ["onUrl", "offUrl"],
+        "properties": {
+          "onUrl": {
+            "type": "string",
+            "title": "Light On URL",
+            "description": "URL to turn on the light."
+          },
+          "offUrl": {
+            "type": "string",
+            "title": "Light Off URL",
+            "description": "URL to turn off the light."
+          },
+          "brightnessUrl": {
+            "type": "string",
+            "title": "Light Brightness URL",
+            "description": "URL to adjust the brightness of the light. (i.e. [GET|POST]:http://mydomain.com/api/device?brightness=${BRIGHTNESS})"
+          },
+          "colorTempUrl": {
+            "type": "string",
+            "title": "Light Color Temperature URL",
+            "description": "URL to adjust the color temperature of the light. (i.e. [GET|POST]:http://mydomain.com/api/device?colorTemp=${COLORTEMP})"
+          },
+          "rgbUrl": {
+            "type": "string",
+            "title": "Light RGB URL",
+            "description": "URL to adjust the RGB color of the light. (i.e. [GET|POST]:http://mydomain.com/api/device?rgb=${RGB})"
+          }
+        }
+      }
+    },
     "debug": {
       "description": "Enable the debug for the plugin.",
       "type": "boolean",

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "matterbridge-webhooks",
-  "version": "1.0.2",
+  "version": "1.1.0-edge.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "matterbridge-webhooks",
-      "version": "1.0.2",
+      "version": "1.1.0-edge.2",
       "license": "Apache-2.0",
       "dependencies": {
         "node-ansi-logger": "3.1.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "matterbridge-webhooks",
-  "version": "1.0.2",
+  "version": "1.1.0-edge.2",
   "description": "Matterbridge webhooks plugin",
   "author": "https://github.com/Luligu",
   "license": "Apache-2.0",