What About Webhooks
For truly interactive IoT applications we need bidirectional event signaling:
Fortunately, LooUQ iotQi has established patterns for both commands (to device) and event webhooks (from device). Webhooks are a lightweight HTTP pattern providing a simple pub/sub model for wiring together Web APIs and SaaS services like LooUQ iotQi; many services such as GitHub, Twitter, SendGrid and Stripe use webhooks to callback to you when service events happen.
When an event happens on a iotQi device, your device can send a priority alert event to the LooUQ cloud. Based on rules you setup for your subscription, a notification is sent to designated recipients. One form of notification is a webhook. For this type of notification, your application will receive a HTTP POST request with a request body containing JSON data originating from your device’s alert.
Using Webhooks with iotQi
With iotQi using webhooks is easy. With just a couple steps your webhooks will be flowing.
To start receiving webhook notifications you will setup one or more notification rules in iotQi Setup. Notification rules apply to your subscription, not individual devices, so with only a handful of notification rules you can be receiving webhooks, text messages, and email notifications.
How exactly you build your webhook receiver will depend primarily on how you intend to use it and exactly what your application will do with the notification information you receive. Regardless of the type of application, you will need to follow a basic set of tasks. The sample webhook receiver on the LooUQ GitHub site has all of the required parts, with numerous comments on how to migrate each function to your application. In summary, the webhook receiver must:
Listen for incoming HTTP POST requests.
Route these requests to logic to unpack the request contents (if your familiar with ASP.NET WebAPI, this is a controller action).
Perform validation on the received content. iotQi signs (optional, but strongly recommended) the outgoing request using a secret you provide.
Execute your business logic to do whatever you intended the webhook to trigger.
Building Your Webhook Receiver
Webhook functionality can be integrated into numerous enterprise application models. For large scale, enterprise you are likely to already be using web-based RESTful API services, which is exactly what a webhook is.
For lighter weight applications you may wish to build your application on workstation based platforms like a Windows console application to write incoming events to a disk log, or a WPF application to serve as a dashboard. For these lighter applications, self-hosting is an option with Microsoft's Katana implementation of OWIN. Self-hosting in this context refers to the ability to run a RESTful web API without the use of a full-fledged web server such as IIS (Internet Information Server). The webhook sample found in LooUQ's GitHub collection is an example of a self-hosted Windows console application.
Obstacles You May Encounter
Anytime you are receiving unsolicited information you are likely to be impacted by firewall settings. For server based implementations IIS will do most of the work to register your web applications appropriately with the supporting system's required resources and configure the necessary settings. If you are building your webhook receiver logic as a self-hosted application you will have to manually complete the short-list of configuration tasks below in order to have a functioning webhook receiver application. The tasks below are for a Windows system.
One of the tricky things to address with remote access is the correct firewall rule to allow the request traffic in. The unique issue is that the actual process on your PC listening for requests is not your application, it is the HTTP.SYS windows process; this is addressed in the rule below by designating "This program path: SYSTEM". In summary setup the firewall rule as follows:
Special thanks to Pieter for this post on Stack Overflow for information on the firewall rule.
HTTP.SYS Listener Settings
When you use IIS, it automatically sets HTTP.SYS to be a listener for the interfaces (addresses) bound to your site applications. If you self-host you may need to adjust settings for your computer as follows:
Start by opening an elevated command prompt (run as administrator)
Review existing IP listen policies with: netsh http show iplisten
Set a new IP listen policy with: netsh http add iplisten ipaddress=<ip_address> (use 0.0.0.0 as the address for all address on your computer)
HTTP.SYS URL ACL Reservations
To receive incoming HTTP traffic, your application must be either 1) running as "administrator", or 2) register with HTTP. I recommend the registration approach.
To setup a HTTP URL ACL registration use the following recommended command line from a elevated command prompt.
netsh http add urlacl http://+:<portNumber>/ user=<yourUserName>
<portNumber> is the port number your application is listening for webhook requests on. The + is the strong-wildcard match for any IP address or host name you are listening on.
<yourUserName> is your windows sign-on name. If your application will be running under a different local account than yours, use that account username instead.
To see your current HTTP.SYS URL reservations, use the following command. You can optionally add the details to filter the list displayed to only include the ones you are interested in (2nd example).
netsh http show urlacl
netsh http show urlacl http://+:9000/
Thanks for reading.