Webhooks

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 to use webhooks

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.

Prerequisites

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.

Permissions

Webhooks get events for objects they have read permissions by the technical users of the Netilion Connect subscription.

Handling Webhooks

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.

Configure Webhooks

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.

Validating payloads

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

• Create a hash using your secret and incoming payload body.
• Compare created hash with the signature value provided in the header.

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

Payload & Event Types

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:

asset_value_created

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"
    }
  }
}

asset_values_created

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"
          }
        ]
      }
    ]
  }
}