Webhooks – expand your options

With Cloud Notify you can receive real-time notifications from your machine(s) in a robust and safe way. By connecting an external application via webhook, you can expand your options even further. Think about a chain of recipients (first person one gets a message, if they don’t respond, person two gets a message), SMS functionality, automated calls, and more.

The use of webhooks in X4 remote is free. However, keep in mind that the external application(s), that you connect to via a webhook, may not be.

What is a webhook?

A webhook is a way for an application to provide external applications with real-time information. It’s sometimes referred to as “reverse API“, because the external application is not requesting the information itself, but is simply being given the information instead. It then needs to be able to interpret this information, because it’s being provided in a certain format. More details on this later.

What can I send?

All messages that you receive in your X4 remote 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.

Add a webhook in X4 remote

Now that you understand what a webhook is and which information you can send via a webhook, you can add a webhook in X4 remote.

  • First you’ll need a webhook URL so X4 remote knows where to send messages to.

Webhook URL?

You can get a webhook URL at the website or service that you want to connect to via webhook (e.g. PagerDuty, Zapier, IFTTT, etc.). On that website you need to follow the appropriate steps to connect via a webhook and it will provide you with a webhook URL. These steps can vary per service.

  • In X4 remote, go to [Messages] in the main menu and open the Message Center settings by pressing the settings icon  in the top right corner.

Press [Add new webhook], enter a name, enter the webhook URL, and press [Add].

Webhook added

New messages in your message center will now be forwarded to the connected external application.

External application configuration

You may still need to configure the external application to properly interpret the information. Please take a look below for an example and description.

Information format

X4 remote sends the information in a specific format. As external application you can use services that can already interpret this information format (e.g. PagerDuty, IFTTT), or use an integration service like Zapier to indirectly connect to numerous other services, like Google Sheets. If you’re really tech-savvy you can even develop your own application, in which case the options are endless.

Below is an example of the Cloud Notify alarm format that is sent via a webhook.

{
"alarmRateLimitTill": null,
"companyId": "2618-3162-2154-8450-3278",
"companyName": "Lenze Product Demo",
"createdOn": "2019-05-10T09:20:58",
"extraInfo": {
"Counter1000Max30": "30",
"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",
"systemLabel": "alarm-medium",
"userId": "8WL2I3FsCO4e",
"userName": "Demo user"
}

Some explanatory details on the above information:

PropertyRemark
createdOnThe timestamp is in ISO 8601 format.
extraInfoThis property contains the value of the variable at the moment the alarm fired – in the example above the variable “Counter1000Max30” had value “30” – and the device name, which often is the project or customer name.
longContentThis is the information that’s entered as “instructions” in the alarm for more information about the alarm situation
shortContentThis is the subject of the message/e-mail
systemLabelThis property indicates the type of message (e.g. “alarm-medium” means a medium priority alarm)