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 subscripe to different event types. Please see the API documentation for all supported types.

When to use webhooks

When you 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 recive 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 Connct 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 user 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 inthe header.

Example code for validation:

class NetilionController < ApplicationController

  def proces
    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

The payload of the webhook contains the event_type and the content. For a new asset value, the payload will look like this:

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