Webhooks
For easy data push integration between Netilion and your application, Netilion provides webhooks. Once 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 types of events. Please see the below for all supported types.
When to use webhooks
If your application needs to be automatically informed about changes and new data in Netilion, you can use webhooks. With webhooks you do not need to poll for new data. Webhooks are asynchronous.
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 is exceeded, the corresponding webhooks will not be called.
Permissions
Webhooks receive events for objects for which the technical user of the Netilion Connect subscription has read permissions.
Handling webhooks
The provided URL must be a publicly accessible https address that handles HTTP POST requests.
Netilion must receive a status code 2XX response from the configured URL to confirm that the notification sent via HTTP POST was successfully delivered. If a webhook times out or returns a different status code, Netilion will retry several times to deliver the event data.
Configure webhooks
To register a webhook, the ID of the client application is required. A client application is generated for each Netilion Connect subscription.
If you do not have the ID, you can get it via the 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/webhooksSee the API documentation for the request body.
You receive the secret in the response. The secret is needed to validate the payload.
Validating payloads
Clients using the webhooks should ensure that requests are coming from Netilion. With every incoming POST request from Netilion, a hash signature is passed in the headers. The following hash signatures are available:
HMAC SHA-1 (deprecated, may be removed in future)
Header name: X-Hub-Signature
Value: sha1=XYZ
HMAC SHA-256
Header name: X-Hub-Signature-Sha256
Value: sha256=XYZ
These signatures can be used to validate that the source of the data is Netilion. The hash signature starts with the used hash e.g. sha256=, indicating that the use of HMAC SHA-256 was used for encryption.
The secret used to create the signatures is automatically generated when a new webhook is created and returned in the API call.
It can be changed using the change secret endpoint. To compute the signature, use the supplied secret as the key and the received payload as the data.
Steps to validate a request
- Create a hash using your secret and the incoming payload body.
- Compare the generated 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-Sha256'].blank? calculated_signature = "sha256=#{OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), 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
endRetry handling
As mentioned above, Netilion will retry multiple times to deliver the event data if the request was not successful.
Netilion will attempt to deliver the data 16 times with an exponentially increasing the delay between attempts. The delay time is random. Netilion will retry to deliver the data for approximately 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=failedMore filtering options are available, please see the API documentationfor details.
By sending the event IDs to:
POST https://api.netilion.endress.com/v1/client_applications/ID/webhooks/webhookID/eventsNetilion will restart sending the data (using the retry mechanism described).
After 6 months Netilion will remove the data for the failed events and a re-submission of older events will not be possible.
Enable/disable webhook
Webhook can be enabled or disabled by the user at any time. However, there are cases where Netilion will automatically disable a webhook. For example, if a webhook event for a particular webhook fails repeatedly over a period of more than two weeks, this will unnecessarily consume the connect subscription request quota. In this case, the contact person of the client application that has that webhook will be notified and the user can review the webhook and take action if necessary.
To enable/disable a webhook, the webhook patch request can be used, e.g. in case of enable:
PATCH https://api.netilion.endress.com/v1/client_applications/{client_application_id}/webhooks/{webhook_id}Request body:
{ "disabled": false}Payload & event types
The payload of the webhook contains the event_type and the content, which is different depending on the event type.
The following event types are currently supported:
asset_value_created
Sent, when a new asset value is created. Each value is sent separately in a webhook call. The payload of this event is as follows:
{ "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" } }}asset_values_created
Is sent whenever new asset values are sent to the Netilion API. Use this webhook if the asset sends multiple values at once, and you prefer to receive them all in one webhook. This webhook sends multiple values grouped by their keys as shown in this example.
Optionally, you can specify the value keys to be sent:
Example request format to retrieve only values with the key pressure or value.
{ "url": "https://my.super.app/netiliondata", "event_types": [ "asset_values_created" ], "properties": { "asset_values_created": [ "pressure", "level" ] }}{ "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" } ] } ] }}instrumentation_values_created
Is sent whenever new values from an asset with an instrumentation are sent to the Netilion API. You can subscribe to this webhook to receive the values as single values or multiple values. This webhook sends multiple values grouped under their keys if as shown in this example, when the values were created with a single request.
Optionally, you can specify the value keys to be sent:
Example request format to retrieve only values with the key pressure or value.
{ "url": "https://my.super.app/netiliondata", "event_types": [ "instrumentation_values_created" ], "properties": { "instrumentation_values_created": [ "pressure", "level" ] }}{ "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" } ] } ] }}asset_updated
Is sent when an asset’s parameters are updated. When creating a webhook, add the asset attributes that value updates that you would like to be notified of.
Example request format to receive 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" ] }}The following attributes are supported for the asset_updated event type:
- serial_number
- description
- production_date
- last_seen_at
- product
- parent
- tenant
- status
If a user doesn’t specify an attribute when subscribing to the webhook, changes to all attributes will be used for notification.
Example payload, when 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" } } }}asset_software_added
Is sent whenever a new software is assigned to an asset.
Payload example:
{ "event_type": "asset_software_added", "occurred_at": "2020-03-04T09:15:00", "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" } }}asset_instrumentation_association_created
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" } }}asset_instrumentation_association_destroyed
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" } }}edge_device_updated
This is triggered when an edge device parameter is updated. You can specify the edge device attributes you want to be notified about when setting up a webhook.
Here’s an example of how to format a request to receive notifications when the status or description of an edge device changes:
{ "url": "https://my.super.app/netiliondata", "event_types": [ "edge_device_updated" ], "properties": { "edge_device_updated": [ "status", "description", "last_seen" ] }}The supported attributes for the edge_device_updated event type are:
- serial_number
- description
- last_seen_at
- tenant
- status
- type
- software_version
If a user doesn’t specify an attribute when subscribing to the webhook, changes to all of the attributes will trigger a notification.
Here is an example payload, when the status has changed:
{ "event_type": "edge_device_updated", "occurred_at": "2021-03-03T19:20:30+01:00", "content": { "edge_device": { "id": 1234, "href": "https://api.netilion.endress.com/v1/edm/edge_devices/1234", "status": { "id": 42, "href": "https://api.netilion.endress.com/v1/edm/edge_device/statuses/42" } } }}You can use the status changed webhook to alert users if an edge device’s status is automatically set to offline. To do this, a developer needs to register the following webhook with a technical user:
{ "url": "https://my.super.app/netiliondata", "event_types": [ "edge_device_updated" ], "properties": { "edge_device_updated": [ "status" ] }}All technical users who have registered to this webhook and who have read access to the specific edge device will receive a notification.
asset_appeared
Is sent whenever a technical user gets read permission on an asset.
Payload example:
{ "event_type": "asset_appeared", "occurred_at": "2020-03-04T09:15:00", "content": { "asset": { "id": 4079332, "serial_number": "BAZINGA0007", "href": "https://api.netilion.endress.com/v1/assets/4079332" }, "user": { "id": 123456, "href": "https://api.netilion.endress.com/v1/users/123456" } }}asset_disappeared
Is sent whenever a technical user lost read permission on an asset. It is sent as well for all subordinate child assets.
Payload example:
{ "event_type": "asset_disappeared", "occurred_at": "2020-03-04T09:15:00", "content": { "asset": { "id": 4079332, "serial_number": "BAZINGA0007", "href": "https://api.netilion.endress.com/v1/assets/4079332" }, "user": { "id": 123456, "href": "https://api.netilion.endress.com/v1/users/123456" } }}This event is sent whenever asset is destroyed and technical user with reporting user role subscribed for such webhook event type.
instrumentation_appeared
Is sent whenever a technical user receives read permission on an instrumentation.
Payload example:
{ "event_type": "instrumentation_appeared", "occurred_at": "2020-03-04T09:15:00", "content": { "instrumentation": { "id": 4079332, "tag": "BAZINGA0007", "href": "https://api.netilion.endress.com/v1/instrumentations/4079332" }, "user": { "id": 123456, "href": "https://api.netilion.endress.com/v1/users/123456" } }}instrumentation_disappeared
Is sent whenever a technical user lost read permission on an instrumentation.
Payload example:
{ "event_type": "instrumentation_disappeared", "occurred_at": "2020-03-04T09:15:00", "content": { "instrumentation": { "id": 4079332, "tag": "BAZINGA0007", "href": "https://api.netilion.endress.com/v1/instrumentations/4079332" }, "user": { "id": 123456, "href": "https://api.netilion.endress.com/v1/users/123456" } }}node_appeared
Is sent whenever a technical user receives read permission on an node.
Payload example:
{ "event_type": "node_appeared", "occurred_at": "2020-03-04T09:15:00", "content": { "node": { "id": 4079332, "tag": "BAZINGA0007", "href": "https://api.netilion.endress.com/v1/nodes/4079332" }, "user": { "id": 123456, "href": "https://api.netilion.endress.com/v1/users/123456" } }}node_disappeared
Is sent whenever a technical user lost read permission on an node.
Payload example:
{ "event_type": "node_disappeared", "occurred_at": "2020-03-04T09:15:00", "content": { "node": { "id": 4079332, "name": "BAZINGA0007", "href": "https://api.netilion.endress.com/v1/nodes/4079332" }, "user": { "id": 123456, "href": "https://api.netilion.endress.com/v1/users/123456" } }}asset_specifications_updated
Is sent when one or more **specifications of an asset are updated, one event is sent per request per webhook, regardless of how many keys have changed in the request. If you want to limit it to a set of keys, you can add the asset_specifications_updated property with the list of keys whose value updates are of interest for notification.
Example request format to retrieve events when the specification my_key1, my_key2, my_key3 of an asset has changed.
{ "url": "https://my.super.app/netiliondata", "event_types": [ "asset_specifications_updated" ], "properties": { "asset_specifications_updated": [ "my_key1", "my_key2", "my_key3" ] }}If a user doesn’t specify an attribute when subscribing to the webhook, changes to any specification will trigger a notification.
Example payload (if only specifications my_key2, my_key_3 have changed within the request):
{ "event_type": "asset_specifications_updated", "occurred_at": "2021-03-03T19:20:30+01:00", "content": { "asset": { "id":23, "href":"https://api.netilion.endress.com/v1/assets/23" "specifications": { "my_key2": { "unit": null, "value": "new_value2", "updated_at": "2021-05-26T12:38:37.743Z", "source_timestamp": null }, "my_key3": { "unit": null, "value": "new_value3", "updated_at": "2021-05-26T12:38:37.697Z", "source_timestamp": null } } } }}event_specifications_updated
Is sent when one or more specifications of an event are updated, one event is sent per request per webhook, regardless of how many keys have changed in the request. If you want to limit it to a set of keys, you can add the event_specifications_updated property with the list of keys whose value updates are of interest for notification.
Example request format to retrieve events when the my_key1, my_key2, my_key3 specification of an event has changed
{ "url": "https://my.super.app/netiliondata", "event_types": [ "event_specifications_updated" ], "properties": { "event_specifications_updated": [ "my_key1", "my_key2", "my_key3" ] }}If a user doesn’t specify an attribute when subscribing to the webhook, changes to any specification will trigger a notification. Example Payload (if only specifications my_key2, my_key_3 have changed within the request):
{ "event_type": "event_specifications_updated", "occurred_at": "2021-03-03T19:20:30+01:00", "content": { "event": { "id":23, "href":"https://api.netilion.endress.com/v1/events/67237" "specifications": { "my_key2": { "unit": null, "value": "new_value2", "updated_at": "2021-05-26T12:38:37.743Z", "source_timestamp": null }, "my_key3": { "unit": null, "value": "new_value3", "updated_at": "2021-05-26T12:38:37.697Z", "source_timestamp": null } } } }}event_created
Is sent when an event is created in Netilion (not to be confused with the technical webhook event).
One webhook event is sent per request per webhook. If you want to limit it to a set of event types, you can add the event_created property with the list of event type codes which new events are of interest for notification.
To get event_created events, the technical user of the client application should have at least read permissions on one of the assets or instrumentations specified in the POST call of the events request.
Example request format to retrieve webhook events when events with type codes heartbeat_verification or device_certificate_renewal are created:
{ "url": "https://my.super.app/netiliondata", "event_types": [ "event_created" ], "properties": { "event_created": [ "heartbeat_verification", "device_certificate_renewal" ] }}If a user doesn’t specify an attribute when subscribing to the webhook, changes to any event creation will trigger a notification.
Example Payload:
{ "event_type": "event_created", "occurred_at": "2021-03-03T19:20:30+01:00", "content": { "event": { "id": 11, "href": "https://api.netilion.endress.com/v1/events/11", "name": "ntestKais", "responsible": 'Hans', "type": { "id": 2, "code": "device_certificate_renewal", "href": "https://api.netilion.endress.com/v1/event/types/2" }, "status": { "id": 1, "code": "scheduled", "href": "https://api.netilion.endress.com/v1/event/statuses/1" }, "assets": [ { "id": 1, "href": "https://api.netilion.endress.com/v1/assets/1" }, { "id": 2, "href": "https://api.netilion.endress.com/v1/assets/2" } ], "instrumentations": [ { "id": 1, "href": "https://api.netilion.endress.com/v1/instrumentations/1" } ], "documents": [ { "id": 3, "href": "https://api.netilion.endress.com/v1/documents/3" } ] } }}event_document_created
Is sent whenever a document is assigned to an event.
Similar to the webhook event_created, a filter based on the event type code can be given to limit the notification to a certain subset of event type codes. Example request:
{ "url": "https://my.super.app/netiliondata", "event_types": [ "event_document_created" ], "properties": { "event_document_created": [ "heartbeat_verification", "device_certificate_renewal" ] }}Payload example:
{ "event_type": "event_document_created", "occurred_at": "2020-03-04T09:15:00", "content": { "event": { "id": 4079332, "href": "https://api.netilion.endress.com/v1/events/4079332" }, "document": { "id": 123456, "href": "https://api.netilion.endress.com/v1/documents/123456" } }}asset_health_condition_updated
Is sent whenever the health conditions linked to an asset changed.
{ "url": "https://my.super.app/netiliondata", "event_types": ["asset_health_condition_updated"]}The webhook payload contains the current status of the asset, the current assigend health conditions and the health conditions assigned before the update.
Payload example:
{ "event_type": "asset_health_condition_updated", "occurred_at": "2020-03-04T09:15:00", "content": { "asset": { "id": 4079332, "href": "https://api.netilion.endress.com/v1/assets/4079332" }, "asset_status": { "code": "failure", "name": "Failure", "description": "string", "id": 2, "tenant": { "id": 1, "href": "https://api.netilion.endress.com/v1/tenants/1" } }, "health_conditions": [ { "diagnosis_code": "F42", "id": 99, "asset_status": { "id": 2, "href": "https://api.netilion.endress.com/v1/asset/status/2" }, "channel": "A", "module": "B", "links": { "causes": { "href": "https://api.netilion.endress.com/v1/health_conditions/99/causes" } } } ], "previous_health_conditions": [ { "diagnosis_code": "M18", "id": 1089, "asset_status": { "id": 1, "href": "https://api.netilion.endress.com/v1/asset/status/1" }, "channel": "Channel 1", "module": "Module 7", "links": { "causes": { "href": "https://api.netilion.endress.com/v1/health_conditions/1089/causes" } } } ] }}product_status_changed
Is sent whenever the product status of a product changed if the user has at least one asset that is linked to the product.
{ "url": "https://my.super.app/netiliondata", "event_types": ["product_status_changed"]}The Webhook payload contains the product and status details.
Payload example:
{ "event_type": "product_status_changed", "occurred_at": "2023-03-24T01:00:00+01:00", "content": { "product": { "href": "https://api.netilion.endress.com/v1/products/54", "id": 54, "product_code": "XYZ", "phase_out_date": "2023-03-24", "order_stop_date": "2025-01-01", "spare_parts_until": "2026-08-04", "spare_sensors_until": "2027-09-18", "repair_until": "2026-01-01", "calibration_until": "2026-03-04", "name": "Example Product", "status": { "href": "https://api.netilion.endress.com/v1/product/statuses/17", "id": 17, "code": "phase_out", "name": "Phase out", "description": "Order stop dates and successor products have been defined.", "tenant": { "id": 1, "href": "https://api.netilion.endress.com/v1/tenants/1" } } } }}threshold_reached
Is sent whenever a given threshold (high or low) reached for a System, Recipe or Instrumentation if the user has at least one asset linked.
{ "url": "https://my.super.app/netiliondata", "event_types": ["threshold_reached"]}The Webhook payload contains the event type threshold_reached, data, relevant thresholdable type(System/ Recipe/ Instrumentation ) and object details.
Payload example:
{ "event_type": "threshold_reached", "occurred_at": "2023-03-24T01:00:00+01:00", "content": { "asset": { "id": 54, "href": "https://api.netilion.endress.com/v1/assets/54" }, "instrumentation": { "id": 55, "href": "https://api.netilion.endress.com/v1/instrumentation/55" }, "data": { "value": 4.0, "key": "temperature", "timestamp": "2023-06-30T13:52:56", "unit": { "code": "degree_celsius", "symbol": "°C" } }, "threshold": { "type": "high", "name": "instruemtation threshold name", "value": 3.8, "unit": { "code": "degree_celsius", "symbol": "°C" }, "thresholdable_type": "Instrumentation", "value_in_threshold_unit": null } }}add_on_node_association_created / add_on_node_association_destroyed
This webhook is sent, when an addon is linked to a node or respectively if such a link is destroyed.
{ "event_type": "add_on_node_association_created", "occurred_at": "2023-08-03T02:00:00+02:00", "content": { "add_on": { "id": 12 } "node": { "id": 11, "href": "http://www.example.org/v1/nodes/11" }, "subscription": { "id": 12, "display_name": "Basic", "user": { "id": 65, "email": "tracy.okuneva@quigleyhickle.biz" }, "billing_address": { "id": 47, "company_name": "Auer and Sons", "street": "Parisian Village", "zip_code": "61061-6713", "city": "West Edythe", "country_code": "IE" }, "material_number": "35984241", "href": "http://www.example.org/v1/subscriptions/12" } }}