Node Red Projects – Setting up a Webhook management system using Node-Red

November 26,2020 in  Engineering
by Andrea Azzarà

Setting up a Webhook management system using Node-Red. Learn how to create a webhook management system using Domotz network monitoring system and Node-RED.

Node Red Webhooks

In need of some new Node Red Projects? You have come to the right place! Today’s tutorial will cover a new Node Red Project – setting up a webhook management system in Node Red using Domotz network monitoring software. 

A couple of weeks ago, I wrote a blog post on how to install and use Node-red-domotz to build a custom Node-Red dashboard for IoT and SNMP data leveraging the Domotz Public API. 

In this tutorial I’ll cover a new Nod Red Project Example:

  • How to set-up a Webhook management system using Node-Red
  • How to enrich the Node Red custom dashboard displaying live Domotz events
  • automatically respond to a network event through the Domotz Public API

Domotz allows you to subscribe to events happening on agents and devices and to receive Webhooks when they occur. You can find more information about Webhook configuration and data format on the Domotz Portal. This tutorial will assume that you have already correctly configured a Shared alert and attached it to at least one agent/device.

Setting-Up the Webhook listener

To be able to receive Webhooks from Domotz you need to expose a web server on a public IP address. The Node-Red installation guide can help you deploying your Node-Red flow on a public server. It is strongly recommended to secure the endpoint, using HTTPS and to set up an authentication mechanism.

Create and test the server

Once Node-Red is started we can create the web server using the http in node. Just drag it into the workspace and configure it with a URL suffix (webhook-test in this case). Method must be POST.

Node Red project setting up a Webhook management system

This is just a receiver node, any HTTP client expects a response so we need to create also a http response node. Domotz Webhook service expects a response with code 201 and an empty body, hence we can directly attach the http response node to to the output of the http in node. Let’s also add a debug node to the same output to monitor the received messages.

Node Red project editing the response Node

Once deployed the flow you can test the endpoint using any HTTP client (curl,Postman) issuing a POST request like the following:

curl --location --request POST 'https://your-node-red-service-ip:1880/webhook-test' \
     --header 'Content-Type: application/javascript' \
     --data-raw '{"test": true}'

Just remember to replace your-node-red-service-ip with the actual IP address of your server and to add the authentication header to the request if needed.

If the configuration is correct this is what you should see in the debug panel.

Webhook management system Node-RED 3

 

Enriching the dashboard

In the previous tutorial we’ve seen how to feed Domotz Public-API data in a Node-Red custom dashboard. In that scenario we used to poll the Domotz Public-API servers using the Domotz Node-Red node. Now we subscribe to Domotz events, receive and display data directly pushed from Domotz into the same dashboard. Keep in mind that the two approaches can happily coexist and they are useful for different purposes.

The following setup is simple but powerful as it allows creating a live event log of everything happening on our Domotz agents. To do that, let’s create a new dashboard template node.

Webhook management system Node-RED 4

You can use the following code in the template to parse and display the incoming Domotz events in a list.

<style>
   li {
       margin: 10px 0;
   }

   time {
       font-size: 10px;
       display: block;
       font-style: italic;
   }

   details {
       display: block;
       font-size: 10px;
   }
</style>

<script>

   (function (scope) {
       scope.$watch('msg', function (msg) {
           if (msg) {
               var list = document.getElementById('myList');
               var entry = document.createElement('li');
               var time = document.createElement('time');
               var details = document.createElement('details');
               
               entry.appendChild(document.createTextNode(msg.payload.name));
               time.appendChild(document.createTextNode(msg.payload.timestamp));
               entry.prepend(time);
               list.prepend(entry);
               details.appendChild(document.createTextNode(JSON.stringify(msg.payload.data, null, 2)));
               entry.append(details);
           }
       });
   })(scope);

</script>

<div>
   <ul id="myList"></ul>
</div>

Each time a new message is received the $watch callback is invoked with the newly-received message. What we do in the callback is to unpack the content of the message into three parts (name, timestamp, and details), which are common to all Domotz Webhooks, and insert them at the top of a simple list. You can see the result in the following image.

Node Red Projects Device Status and Device IP change log of live events

 

Advanced event parsing and automatic reaction

In the previous example we treated each message in the same way, taking its content and displaying it in a dynamic list. If we want to respond to a specific event then we need to define a custom parsing function. 

In the next example we chain a webhook event handler (Round-Trip-Delay issue on a device) with a Public API call (restarting the device itself). The RTD issue event is described here and is generated when Domotz detects that the RTD values exceeds the defined thresholds. We then use the powerActionOnDevice API call to perform a power cycle on the device. The following images display the wiring and configuration of the nodes.

Webhook management system Node-RED 6

A function node is needed to:

  • filter the unrelated webhook events (we are only interested in events named device_rtd)
  • extract the information required to perform a reboot (agent_id and device_id) from the event body

The information we extracted are returned as output of the function node and become the input of the API node (remember to check the Use node input params option in the Domotz node in this case. You can use the following code in the function node:

if (msg.payload.name === 'device_rtd' && 
    msg.payload.data.status === 'RTD_ISSUE_DETECTED') {
    return {
        "payload": {
            "params": {
                "agent_id": msg.payload.data.agent_id,
                "device_id": msg.payload.data.device_id,
                "field": "cycle"
            }
        }
    };
}

That’s it, the next time a RDT event will be detected by Domotz our flow will automatically reboot the device.

Node Red Webhook Management System Testing Tips

Waiting for a webhook from Domotz can be really boring.,After all,they are only triggered when something really happens on your networks and waiting for that to happen could take some time

If you are interested in developing a Webhook handler a quick way to test your integration is to generate fake events using an HTTP client (as described before). You can forge a body simply copying the Events examples provided in the schemas section of the documentation

Node-Red can be a powerful tool to customise your Domotz experience. In conjunction with the Node-red-domotz plugin and the Domotz Webhook service it allows you to create custom application logics and beautiful custom node red dashboards.

Further Node Red Project reading: