For easy data push integration between Netilion and your application, Netilion offers webhooks. When configured, a webhook is used to send out notifications to your service. Once you have configured a URL, Netilion will post the event data as JSON to your webhook URL. You can subscribe to different event types. Please see the API documentation for all supported types.
When your application needs to get informed automatically about changes and new data in Netilion, you can use webhooks. With webhooks you do not need to poll for new data. Webhooks are posted asynchronously.
To receive webhooks, you need an active Netilion Connect subscription with at least one API key. Calls and payload size will be added to the quota usage of the Connect subscription. If the quota exceeds, the corresponding webhooks will not be called.
Webhooks get events for objects they have read permissions by the technical users of the Netilion Connect subscription.
The provided URL must be a public accessible https address that handles HTTP POST requests.
Netilion needs to get a status code 2XX reply from the configured URL to confirm that the notification sent via HTTP POST has been successfully delivered. If any webhook times out or another status code was returned, Netilion will retry multiple times to deliver the event data.
To register a webhook, the ID of the Client Application is needed. With every Netilion Connect subscription a client application is generated. If you do not already have the ID, you can find it via API GET https://api.netilion.endress.com/v1/client_applications?name=YOURDEFINEDNAME
With this ID you can register your Webhook (via POST https://api.netilion.endress.com/v1/client_applications/ID/webhooks
, see API documentation for rerquest body) and will get the secret in the response. The secret is needed for validating the payload.
Clients using the webhooks should ensure that requests come from Netilion. With each incoming POST request from Netilion, a hash signature will be passed in the headers as X-Hub-Signature
. This signature can be used to validate the source of the data is Netilion. The hash signature starts with sha1
=, indicating the use of HMAC SHA-1 to encrypt. The secret used to create the signature is generated automatically when a new webhook is created and returned in the API call. It can be changed with the change secret endpoint. To calculate the signature, use the provided secret as key and the received payload as data
Steps to validate a request
Example code for validation:
class NetilionController < ApplicationController
def process
raise AuthenticationFailed if request.headers['X-Hub-Signature'].blank?
calculated_signature = "sha1=#{OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), ENV['webhook_secret'], request.raw_post)}"
raise AuthenticationFailed unless Rack::Utils.secure_compare(calculated_signature, request.headers['X-Hub-Signature'])
event = JSON.parse(request.body.string)
.....
end
end
The payload of the webhook contains the event_type and the content, which is different depending on the event type.
Currently, following event types are supported:
Will be sent, when a new asset value gets created. Each value will be sent separately in a webhook call. The payload of this event looks like the following:
{
"event_type": "asset_value_created",
"content": {
"asset": {
"id": 4079332,
"href": "https://api.netilion.endress.com/v1/assets/4079332"
},
"value": {
"key": "level",
"group": "measurement",
"unit": {
"id": 8594,
"href": "https://api.netilion.endress.com/v1/units/8594"
},
"timestamp": "2020-03-04T08:38:25Z",
"value": "96.45"
}
}
}
Is sent whenever new asset values are sent to the hub. Use this webhook if the asset sends several values at once, and you prefer to recieve them all in one webhook. This webhook sends multiple values grouped under their keys as shown in this example.
{
"event_type": "asset_values_created",
"content": {
"asset": {
"id": 4079332,
"href": "https://api.netilion.endress.com/v1/assets/4079332"
},
"values": [
{
"key": "volumeflow",
"group": "measurement",
"unit": {
"id": 8594,
"href": "https://api.netilion.endress.com/v1/units/8594"
},
"data": [
{
"timestamp": "2020-03-04T08:38:25Z",
"value": "88.99"
},
{
"timestamp": "2020-03-04T08:38:25Z",
"value": "90.00"
}
]
}, {
"key": "pressure",
"group": 'measurement',
"unit": {
"id": 222,
"href": "https://api.netilion.endress.com/v1/units/222"
},
"data": [
{
"timestamp": "2020-03-04T08:38:25Z",
"value": "88.99"
},
{
"timestamp": "2020-03-04T08:38:25Z",
"value": "90.00"
}
]
}
]
}
}