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.

  1. Search online and choose a third-party application whose services you wish to use.
  2. Get the webhook URL from the third-party application you wish to use.
  3. In the X4, go to Messages > Settings > Configure webhooks.
  4. 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.

  5. 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.

  1. 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.
  2. Go to Messages > Settings > Configure webhooks and open your webhook. If you already had your webhook open, refresh the contents of the Trigger log.
  3. 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.

 

 

Užklausimo forma