INSTAR Cloud

Webhook

Smarthomes and automation system often provide HTTP Webhooks to interconnect with third-party systems. Configure your INSTAR Cloud to contact such a webhook when an alarm is being recorded.

Example: Using the INSTAR Cloud Webhook with Node-RED

Setting up a Webhook

We have several tutorials on how to use your INSTAR cameras Alarmserver to contact your smarthome system through a webhook (e.g. Node-RED, ioBroker or Home Assistant). The same webhook can used with your INSTAR Cloud account.

The one big difference here is, that the webhook needs to be accessible from the internet to be connected to your cloud account. Luckily, every INSTAR IP camera has it's own DDNS address that can be "misused" here.

Hinweis:

Before forwarding a port to your home automation system always make sure that access to it is password protected! In case of e.g. Node-RED you both have to protect your Node-Red user interface by setting the adminAuthand also the httpNodeAuth variable to protect the webhook itself. Both can be set inside the setting.js file.

Start by forwarding your smarthomes HTTP port - the default for Node-RED is 1880 - to the server IP address that runs your smarthome system. It makes sense here to change the default port or - if your router allows you to do that e.g. an AVM Fritzbox - use the default port inside your local network, but set external port to something else.

Now you can use the DDNS address of ANY INSTAR IP camera on the same network as your smarthome to connect to call the webhook over the internet. You can try the webhook from a PC or cellphone that is not connected to your local network. Are you able to trigger the webhook? If yes, we are now able to add it to our INSTAR Cloud account.

Configuring your INSTAR Cloud

You can find the webhook configuration in Alarm Settings under Webhook:

INSTAR Cloud - Webhook

Add your webhook as configured above - don't forget to add your HTTP login at the bottom of the configuration page - in case of Node-RED this will be the user login you added as httpNodeAuth:

INSTAR Cloud - Webhook

As you can see above the INSTAR Cloud can add both the recognized alarm trigger as well as the Cloud ID of your camera as URL queries to the webhook request. To simulate this I will - for now - add a parameter cam = cameraid and object = 1. You will have to remove both once you actually start using the hook. But this allows us to hit the Test button below and see what a "real" alarm will look like inside our smarthome!

When I hit the Test button I get the message that the INSTAR Cloud is able to access my webhook:

INSTAR Cloud - Webhook

Working with URL queries

On our smarthome side we can now use the Cloud trigger to add an action of our choice - send a message to your favourite messenger, sound an alarm bell, etc. But we can also extract the parameters that the INSTAR Cloud adds to the request. As mentioned above, I added these manually for now. This way we can simply hit the Test button to simulate an event. Here is an example how this can be done in Node-RED:

INSTAR Cloud - Webhook

Flow Export:

[{"id":"38b7bc1d.686704","type":"http response","z":"ed9ce5b007555c56","name":"","x":470,"y":40,"wires":[]},{"id":"eb3f53ec.7ccc8","type":"template","z":"ed9ce5b007555c56","name":"page","field":"payload","fieldType":"msg","format":"handlebars","syntax":"mustache","template":"<html>\n    <head></head>\n    <body>\n        <h2>Trigger: {{req.query.trigger}}</h2>\n        <h2>Camera: {{req.query.cam}}</h2>\n        <h2>Object: {{req.query.object}}</h2>\n    </body>\n</html>","x":350,"y":40,"wires":[["38b7bc1d.686704"]]},{"id":"679c2568.c1aa9c","type":"http in","z":"ed9ce5b007555c56","name":"Webhook with URL Query","url":"/as-webhook/","method":"get","upload":false,"swaggerDoc":"","x":115,"y":60,"wires":[["eb3f53ec.7ccc8","d47269ed.fe6118"]]},{"id":"bedc0285.722dd","type":"switch","z":"ed9ce5b007555c56","name":"trigger","property":"payload.trigger","propertyType":"msg","rules":[{"t":"eq","v":"camera","vt":"str"},{"t":"eq","v":"cloud","vt":"str"}],"checkall":"true","repair":false,"outputs":2,"x":270,"y":120,"wires":[["642a98e9cbc7ac4a"],["376ebc65.1998a4"]]},{"id":"d47269ed.fe6118","type":"function","z":"ed9ce5b007555c56","name":"extract query","func":"msg.payload = msg.req.query;\nreturn msg;","outputs":1,"noerr":0,"x":126,"y":120,"wires":[["bedc0285.722dd"]]},{"id":"376ebc65.1998a4","type":"switch","z":"ed9ce5b007555c56","name":"Cloud","property":"payload.cam","propertyType":"msg","rules":[{"t":"eq","v":"cameraid","vt":"str"},{"t":"else"}],"checkall":"true","repair":false,"outputs":2,"x":150,"y":200,"wires":[["0c56e9b0ed94f542"],["3d07c6095e1f1d38"]]},{"id":"642a98e9cbc7ac4a","type":"debug","z":"ed9ce5b007555c56","name":"","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"false","statusVal":"","statusType":"auto","x":430,"y":100,"wires":[]},{"id":"cda26d9f76231263","type":"debug","z":"ed9ce5b007555c56","name":"","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"false","statusVal":"","statusType":"auto","x":590,"y":160,"wires":[]},{"id":"885b843387e73f9c","type":"switch","z":"ed9ce5b007555c56","name":"Object","property":"payload.object","propertyType":"msg","rules":[{"t":"eq","v":"Person","vt":"str"},{"t":"else"}],"checkall":"true","repair":false,"outputs":2,"x":450,"y":180,"wires":[["cda26d9f76231263"],["90e220e412005b1b"]]},{"id":"0c56e9b0ed94f542","type":"change","z":"ed9ce5b007555c56","name":"cameraid","rules":[{"t":"change","p":"payload.object","pt":"msg","from":"0","fromt":"str","to":"Unknown","tot":"str"},{"t":"change","p":"payload.object","pt":"msg","from":"1","fromt":"str","to":"Person","tot":"str"},{"t":"change","p":"payload.object","pt":"msg","from":"2","fromt":"str","to":"Vehicle","tot":"str"},{"t":"change","p":"payload.object","pt":"msg","from":"3","fromt":"str","to":"Person & Vehicle","tot":"str"},{"t":"change","p":"payload.object","pt":"msg","from":"4","fromt":"str","to":"Animal","tot":"str"},{"t":"change","p":"payload.object","pt":"msg","from":"5","fromt":"str","to":"Person & Animal","tot":"str"},{"t":"change","p":"payload.object","pt":"msg","from":"6","fromt":"str","to":"Vehicle & Animal","tot":"str"},{"t":"change","p":"payload.object","pt":"msg","from":"7","fromt":"str","to":"Person, Vehicle & Animal","tot":"str"}],"action":"","property":"","from":"","to":"","reg":false,"x":320,"y":180,"wires":[["885b843387e73f9c"]]},{"id":"90e220e412005b1b","type":"debug","z":"ed9ce5b007555c56","name":"","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"false","statusVal":"","statusType":"auto","x":590,"y":200,"wires":[]},{"id":"3d07c6095e1f1d38","type":"debug","z":"ed9ce5b007555c56","name":"","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"false","statusVal":"","statusType":"auto","x":330,"y":220,"wires":[]}]

In this flow I created a webhook on /as-webhook/. I extract the queries from incomming GET requests and sort them by trigger. If the trigger is cloud I continue sorting by cam (the camera ID of the camera that caused the alarm) and object (the appened alarm trigger). I additionally added a Change Node that allows me to replace the number scheme that the INSTAR Cloud is using with the name of the detect object:

Object CodeDescription
0Unknown
1Person
2Vehicle
3Person & Vehicle
4Animal
5Person & Animal
6Vehicle & Animal
7Person, Vehicle & Animal

As you can see the resulting message object is:

{"trigger":"cloud","cam":"cameraid","object":"Person"}

And I am now able to add different actions depending on what camera triggered the alarm and what object was detected in the alarm video.

Testing

Remove the cam and object parameter from your webhook configuration and wait for the next alarm event registered by your cameras:

INSTAR Cloud - Webhook

Our cat triggered an alarm recording, was recognized by the object detection and the webhook was sucessfully contacted!

INSTAR Forum

Discuss this article on the INSTAR Forum !