Expand on notifications: call, sms and more, using webhooks

It might be desirable to expand on the messaging capabilities of x4 Remote Cloud. For example, to forward the notifications to a ticketing system or alert via SMS, Whatsapp, voice call, and more. This can be achieved by using a webhook to automatically send the notifications to a third-party application. In the third-party application you then configure which action to take. There are no additional costs for using webhooks in x4 Remote Cloud. However, third-party applications may charge a fee for using their services.

What messages are sent?

All messages that the user receives in their message center are sent to the webhook URL, in real-time. This includes:

Machine alarm: when any Cloud Notify alarm is triggered.
Device transfer: when a device from your company is transferred to another company.

Configure a webhook

Important notes and tips:

Webhooks cannot be managed for your x4 Remote Cloud company as a whole. Instead, you configure a webhook for your x4 Remote Cloud user account. Every message that you receive will be sent to the webhook URL. See What messages are sent? for more information.
Create a separate account in the x4 Remote Cloud to configure the webhook on, instead of using an existing user account. This prevents that a webhook notification stops working or can no longer be managed when one person leaves the company.
Create a filter to not receive an e-mail or push notification. This way the message is still sent to the webhook, but you don't get an e-mail or push notification about it. In the third-party application you can then configure if and when you get notified about messages.

Please follow the steps below to configure your webhook.

Search online and choose a third-party application whose services you wish to use.
Get the webhook URL from the third-party application you wish to use.
In the X4, go to Messages > Settings > Configure webhooks.

Add a new webhook and enter the required fields:

Field	Description
Name	A descriptive name for the webhook.
URL	The third-party webhook URL. HTTPS is required (HTTP is not supported). The URL is allowed contain a port and path. Not every URL is a webhook URL. Please consult the documentation of the third-party application to verify it is a webhook URL and not a regular URL.

Go back to the third-party application and configure what action needs to be taken when a specific webhook message is received. For detailed instructions please consults the links above or view the third-party's own documentation.

Below you'll find helpful details to assist you in your configuration.

Webhook message details
POST message example

        {   "Timestamp": "2022-07-07T13:57:11.486719Z",   "Method": "POST",   "RemoteAddr": "127.0.0.1:20095",   "ID": 6551045966659584,   "Headers": {     "Accept": [       "application/json, application/xml, application/html;q=0.9, */*;q=0.8"     ],     "Accept-Encoding": [       "gzip"     ],     "Content-Length": [       "525"     ],     "Content-Type": [       "application/json"     ],     "Forwarded": [       "for=\"64.227.71.156\";proto=https"     ],     "Traceparent": [       "00-0d7d99d9b82371caa4f440b082293956-141ab67042e72b9e-00"     ],     "User-Agent": [       "Webhooks v1.0"     ],     "X-Cloud-Trace-Context": [       "0d7d99d9b82371caa4f440b082293956/1448670823428074398"     ],     "X-Forwarded-For": [       "64.227.71.156, 169.254.1.1"     ],     "X-Forwarded-Proto": [       "https"     ],     "X-Google-Apps-Metadata": [       "domain=gmail.com,host=ptsv2.com"     ],     "X-Webhook-Id": [       "1de77933-698f-45d0-b52f-702087177e7c"     ]   },   "FormValues": {},   "Body": "{\"shortContent\": \"VPN turned to ON of Packager was triggered at 7/7/22, 1:57 PM UTC\", \"longContent\": \"Instructions: VPN is turned on because the switch is turned on (high input)\", \"userId\": \"nmFdkBhI8eoi\", \"userName\": \"IXON Engineer\", \"companyId\": \"8040-7659-1181-9782-2274\", \"companyName\": \"IXON Support Testing\", \"extraInfo\": {\"Device ID\": \"Ss80MfTQt1p7\", \"Device name\": \"Packager\", \"digital input\": \"True\"}, \"alarmRateLimitTill\": null, \"createdOn\": \"2022-07-07T13:57:09+00:00\", \"systemLabel\": \"alarm-low\"}",   "Files": null,   "MultipartValues": null }

POST message body in JSON format

        {   "shortContent": "VPN turned to ON of Packager was triggered at 7/7/22, 1:57 PM UTC",   "longContent": "Instructions: VPN is turned on because the switch is turned on (high input)",   "userId": "nmFdkBhI8eoi",   "userName": "IXON Engineer",   "companyId": "8040-7659-1181-9782-2274",   "companyName": "IXON Support Testing",   "extraInfo": {     "Device ID": "Ss80MfTQt1p7",     "Device name": "Packager",     "digital input": "True"   },   "alarmRateLimitTill": null,   "createdOn": "2022-07-07T13:57:09+00:00",   "systemLabel": "alarm-low" }

Content details

HTTP headers	Description
User-Agent	This will always contain the webhooks version (e.g. WebHooks v1.0) to indicate that the sending party (IXON) is a webhook system.
X-Webhook-Id	A unique ID for the webhook trigger (format UUIDv4). It can be used to make sure that multiple POST requests for the same trigger are only handled once.
Content-Type	The data-type of the request, which is JSON.
Property	Description
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.

Test a webhook

You can test your webhook by triggering one of your Cloud Notify alarms.

Tip
Create a temporary test webhook (use a test webhook URL, e.g. one from webhook.site) to view the exact contents of your specific webhook message.

Create a condition on your machine that triggers one of your configured Cloud Notify alarms. Unfortunately, there is no test option in the x4 Remote Cloud, so you'll need to simulate an actual alarm situation on the machine. Alternatively, you can also transfer a device, because that will also create a message in your message center.
Go to Messages > Settings > Configure webhooks and open your webhook. If you already had your webhook open, refresh the contents of the Trigger log.

Click below for an overview of response codes in the Trigger log.
Response codes

Status code	Description
ok	The webhook message was succesfully received by the webhook URL (HTTP 200 OK).
non-ok-response-code	The webhook URL replied with a message that is not HTTP 200 OK. Make sure the webhook URL is entered correctly, accessible, and is effectively a webhook URL. Please consult the documentation of the third-party application to verify it is a webhook URL and not a regular URL. The webhook message will be sent again. Up to 10 messages are sent per webhook trigger, with an exponentially increasing interval (2min, 4min, 8min, etc), until an "ok" response is received.
too-many-redirects	More than 10 redirects occurred after sending the webhook message and no "ok" response has been received. This error is to prevent a possible infinite redirect loop.
invalid-https	A connection using HTTPS was not possible. Perhaps the webhook URL does not support HTTPS.
could-not-connect	Unable to connect to the webhook URL. The address may be incorrect or there may not be an HTTPS server running.
timeout	The webhook timeout has expired. No response was received within 10s. The webhook message will be sent again. Up to 10 messages are sent per webhook trigger, with an exponentially increasing interval (2min, 4min, 8min, etc), until an "ok" response is received.

I don't see any triggers in my trigger log

Check if you have a filter configured that prevents the webhook from being sent or immediately deletes the message from your message center. Remove that filter.
Check your message center to make sure you actually received a message. All messages that you receive in your message center are sent to the webhook URL. If you did not receive a message, no webhook message will be sent.

Unable to find the answer to your question? Contact us.