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.
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.
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:
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:
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:
Extended Object Detection
Beside the regular - included - object detection for persons, cars and animals the INSTAR Cloud also offers face and license plate detection add-ons. When activated the results from those detections can also be appened as queries here.
Cloud Storage
With each object detection, the Webhook service provides an info about the current level of your cloud account. This is ideal for visualization in Smarthome widgets:
Please note that the INSTAR Cloud deletes files released for deletion in intervals and that alarm videos require more storage space than the pure file size of the uploaded alarm recording due to the processing and provision in different formats.
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:
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 Code | Description |
|---|---|
| 0 | Unknown |
| 1 | Person |
| 2 | Vehicle |
| 3 | Person & Vehicle |
| 4 | Animal |
| 5 | Person & Animal |
| 6 | Vehicle & Animal |
| 7 | Person, 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:
Our cat triggered an alarm recording, was recognized by the object detection and the webhook was sucessfully contacted!
Discuss this article on the INSTAR Forum !