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
endThe 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",
"occurred_at": "2020-03-04T09:15:00",
"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",
"occurred_at": "2020-03-04T09:15:00",
"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"
}
]
}
]
}
}Is sent whenever new values of an asset with an instrumentation are sent to the hub. Use can register to this webhook to receive the values for single values or if several values are send at once. This webhook sends multiple values grouped under their keys if as shown in this example, if the values were created with one request.
{
"event_type": "instrumentation_values_created",
"occurred_at": "2020-03-04T09:15:00",
"content": {
"instrumentation": {
"id": 4079332,
"href": "https://api.staging-env.netilion.endress.com/v1/instrumentations/4079332"
},
"values": [
{
"key": "level",
"group": "measurement",
"unit": {
"id": 8594,
"href": "https://api.staging-env.netilion.endress.com/v1/units/8594"
},
"data": [
{
"timestamp": "2020-03-04T08:38:25Z",
"value": 96.45
},
{
"timestamp": "2020-03-04T09:00:00Z",
"value": 100.00
}
]
},
{
"key": "temperature",
"group": "measurement",
"unit": {
"id": 123,
"href": "https://api.staging-env.netilion.endress.com/v1/units/123"
},
"data": [
{
"timestamp": "2020-03-04T09:00:00Z",
"value": 19.5
}
]
}
]
}
}Is sent when parameters of an asset get updated. When creating a webhook, add the asset attributes which value updates that you prefer to get notified of.
Example request format to get events when the status or the description of an asset has changed
{
"url": "https://my.super.app/netiliondata",
"event_types": [
"asset_updated"
],
"properties": {
"asset_updated": [
"status", "description"
]
}
}For asset_updated event type below attributes are supported.
If a user doesn't add any attribute specifically when registering to the webhook, changes of the all above-mentioned attributes will use for notification
Example Payload (if the status has changed):
{
"event_type": "asset_updated",
"occurred_at": "2021-03-03T19:20:30+01:00"
"content": {
"asset": {
"id": 67237,
"href": "https://api.netilion.endress.com/v1/assets/67237"
"status": {
"id": 42,
"href": "https://api.netilion.endress.com/v1/asset/status/42"
}
}
}
}Is sent whenever a new software is assigned to an asset.
Payload Example:
{
"event_type": "asset_software_added",
"content": {
"asset": {
"id": 4079332,
"href": "https://api.netilion.endress.com/v1/assets/4079332"
},
"software": {
"id": 123456,
"href": "https://api.netilion.endress.com/v1/softwares/123456"
}
}
}Is sent whenever a new association between asset and instrumentation is created.
Payload Example:
{
"event_type": "asset_instrumentation_association_created",
"occured_at": "2021-03-03T19:20:30+01:00",
"content": {
"asset": {
"id": 4079332,
"href": "https://api.netilion.endress.com/v1/assets/4079332"
},
"instrumentation": {
"id": 123456,
"href": "https://api.netilion.endress.com/v1/instrumentations/123456"
}
}
}Is sent whenever a association between asset and instrumentation is destroyed.
Payload Example:
{
"event_type": "asset_instrumentation_association_destroyed",
"occured_at": "2021-03-03T19:20:30+01:00",
"content": {
"asset": {
"id": 4079332,
"href": "https://api.netilion.endress.com/v1/assets/4079332"
},
"instrumentation": {
"id": 123456,
"href": "https://api.netilion.endress.com/v1/instrumentations/123456"
}
}
}Is sent whenever a technical user gets read permission on an instrumentation.
Payload Example:
{
"event_type": "instrumentation_appeared",
"occurred_at": "2020-03-04T09:15:00",
"content": {
"instrumentation": {
"id": 4079332,
"href": "https://api.netilion.endress.com/v1/instrumentations/4079332"
},
"user": {
"id": 123456,
"href": "https://api.netilion.endress.com/v1/users/123456"
}
}
}Is sent whenever a technical user lost it's read permission on an instrumentation.
Payload Example:
{
"event_type": "instrumentation_disappeared",
"occurred_at": "2020-03-04T09:15:00",
"content": {
"instrumentation": {
"id": 4079332,
"href": "https://api.netilion.endress.com/v1/instrumentations/4079332"
},
"user": {
"id": 123456,
"href": "https://api.netilion.endress.com/v1/users/123456"
}
}
}As mentioned, Netilion will retry multiple times to deliver the event data if the request was not successful.
Netilion will try to deliver the data 16 times with exponential increasing waiting time between attempts. The waiting time has a randomness, but Netilion will retry to deliver the data for approx. 3 days.
After that, it is possible to manually resend the events to the receiver. Finding the failed events is possible via GET https://api.netilion.endress.com/v1/client_applications/ID/webhooks/webhookID/events?status=failed (more filter options are available, please see API documentation for details). By sending the event IDs to POST https://api.netilion.endress.com/v1/client_applications/ID/webhooks/webhookID/events, Netilion will restart to send the data (with the described retry mechanism). After 6 months, Netilion will remove the data for the failed events and a resending of older events is not possible.