It might be necessary to expand the messaging capabilities of IXON Cloud. For example, to forward the notifications to a ticketing system, SMS, or an automatic call system. This can be achieved by using a webhook. A webhook is a way for one application to provide another application with real-time information by calling a URL with a data payload. This way notifications can be forwarded to any third-party application that supports webhooks. All that is required, is to enter the webhook URL in IXON Cloud. Once configured, notifications are automatically sent to the third-party application by using the webhook. Some examples of these third-party applications are IFTTT, iLert, PagerDuty, SIGNL4 and Zapier.
All messages that are received in the message center can be forwarded via a webhook, in real-time. This includes:
- When a device from your company is transferred to another company.
- When any Cloud Notify alarm has been triggered.
The first step is to get the URL for the webhook from the third-party application. External articles are available for the following providers:
Webhooks can be added and modified by pressing the cogwheel in the top-right corner of Messages and selecting Configure webhooks. Multiple webhooks can be configured. Every webhook has the following options:
- Name: Name of the webhook
- URL: The URL to call the webhook on
When the URL is called a data package in JSON format is sent. This package contains the data that can be used in the third-party application. The example below gives an overview of all data properties that are used.
"companyName": "IXON Product Demo",
"Device ID": "Txv221Us6poE",
"Device name": "Project #D4 - Alarming machine"
"longContent": "Instructions: Your machine entered an alarm state. Please turn the machine off, open valve D5, and clear any dirt. Reset the alarm afterwards to resume production.",
"shortContent": "Alarm every 30s of Project #D4 - Alarming machine was triggered at 5/10/19, 9:20 AM UTC",
"userName": "Demo user"
Explanation of the properties that are used:
- alarmRateLimitTill: If the alarm is triggered too often, it is stopped until this time.
- companyId: The company ID, which can be found under Admin > Identity > Identity.
- companyName: The company name, which can be found under Admin > Identity > Identity.
- createdOn: The date and time the alarm is triggered, which is in ISO 8601 format.
- extraInfo: This property contains the value of the variable at the moment the alarm was triggered. In the example above the variable Counter1000Max30 had value 30. It also shows the Device ID and Device name.
- longContent: This is the information from the Instructions-field, which is configured on the Alarm trigger.
- shortContent: The subject of the notification message.
- systemLabel: The type of the message. E.g. alarm-medium indicates a Medium priority alarm, which is configured in the Alarm trigger.
- userId: The ID of the user, which can be found in the URL of the page when editing the user under Portal > Users.
- userName: The name of the user, which can be found under Portal > Users.
- Not every API is a webhook. Please consult the documentation of the third-party application to see if a webhook is explicitly mentioned.
- When testing webhooks and they don't arrive, make sure that notifications arrive in the message center. This will confirm that at least the alarms have been configured properly and are triggered. Besides generating an alarm to trigger a notification, it is also possible to transfer a device to trigger a notification.
- There are no additional costs for using webhooks in IXON Cloud. However, third-party applications may charge a fee when using their services.
- Instead of using webhooks to forward notifications to SMS, it might be more beneficial to install the IXON Portal mobile app and receive push notifications.
- A webhook is configured in a user's message center. If a webhook is used for notifications to multiple people, e.g. a department, it is advisable to create a separate account in IXON Cloud to configure the webhook, instead of using an account that is used day-to-day. This prevents that a webhook notification stops working when one person leaves the company account. With some e-mail providers, it is possible to create an extra account by using an e-mail alias. This can be done by adding +something to the e-mail address when registering the account. E.g., firstname.lastname@example.org.