Endpoints: Webhooks

Omnilert provides the ability to post alerts as "Webhooks" messages. Webhooks are user-defined HTTP callbacks that can be used to post Omnilert alerts to your own local server. 

When an Omnilert message is sent to the Webhooks endpoint, Omnilert makes an HTTP request to the URI configured for the webhook endpoint. That server will then receive and process the message in any number of custom applications; such as scrolling displays, website tickers, beacons, etc. 

Configuring Webhook Endpoint

The Omnilert webhook endpoint's configuration uses simple JSON to customize the connection, payload, and parameters sent to the listening server.

The Omnilert Webhooks Endpoint's JSON will define how Omnilert communicates with your server. Only two items are required ('url' and 'method'). The rest are optional.

JSON parameters:

The Omnilert Webhooks Endpoint's JSON will define how Omnilert communicates with your server. Only two items are required (url and method). The rest are optional, unless you are passing data to the URL, then either postData or params will also be required.

When using the 'POST' method, we recommend always including a postData element with any data being sent included in this section of the configuration.

Example Webhooks JSON scripts:

Due to the highly customizable nature of this endpoint, there is no "one configuration" that fits all cases. Your setup will depend entirely on what the destination server ('url') is expecting to receive.

Use the following examples to help guide you in creating your own custom JSON scripts for Webhooks. 

Sending a simple GET request (example) 

At a bare minimum, you must define a "URL" and "method" for Omnilert to send a request to when the webhook endpoint is used. So, it is possible to set up the webhook as simple as just a URL (e.g. "https://yourserver.com/") and the method (e.g. "GET").  

In this example, Omnilert will make a HTTP GET request to the URL (yourserver.com) when the webhook endpoint is engaged. 

Example

{
    "url": "https://yourserver.com/",
    "method": "GET"
}

Naturally, this type of configuration does not pass any message content or parameters with the GET request. This may be all that is needed for your receiving server to do what it needs to do. 

However, it's likely that the receiving side will need more than just an empty GET request. We'll see how to pass message content (via text variables) and hard-coded content in the examples below. 

HTTP GET method example with hard-coded 'params'

The following example sends a GET request including a simple parameter ("var" with the value "HELLO WORLD")  in the 'params' section. 

Example

{
    "url": "https://app.yourserver.com/hooks-api/",
    "method": "GET",
    "params": {
        "var": "HELLO WORLD"
        }
}

Naturally, this is a very simple example as it will send the same hard-coded "HELLO WORLD" content every time an Omnilert webhook message is sent.  In the following sections, we'll learn how to merge the message content from Omnilert's outgoing text messages into your webhook endpoint.

Webhooks Variables

Omnilert can pass the subject and message body sections from your outgoing alerts (See step 3 of Send Message) to the Webhook endpoint for use in 'params' and/or 'postData'.  

Insert text variables inside curly braces within your 'postData' or 'params' to include dynamic content in your webhooks.

You can also insert date/time stamps and other variable text into webhook messages. (See: Text Variables)

HTTP GET with variable params

The following example sends a GET request including the subject and message as parameters.

Example

{
    "url": "https://app.yourserver.com/hooks-api/",
    "method": "GET",
    "params": {
        "subject": "{{webhook_subject}}",
        "message": "{{webhook_body}}"
        }
}

HTTP POST with message content as JSON

In the example below, Omnilert is set to POST data as JSON content with two data items, as follows:

• • Insert the Omnilert message's subject into the field called "title"
  • Insert the Omnilert message's body into the field called "text"

Example

{
    "url": "https://app.yourserver.com/hooks-api/post",
    "method": "POST",
    "headers": {
        "Content-Type": "application/json"
    },
    "postData": {
        "title": "{{webhook_subject}}",
        "text": "{{webhook_body}}"
    }
}

Using this example, whenever you send an Omnilert message to your webhook endpoint, Omnilert will post to your server with the subject sent as the field 'title' and the message body sent as the field 'text'. 

Passing Omnilert content via Authenticated POST (JSON)

This example is much like the above, except this one passes a username ("jdoe") and password ("p@55w0rd") as BASIC AUTH.  This will allow you to send messages to servers that expect a login for all posts.

The data will be posted to the server as JSON using 'application/json' as the 'Content-Type'. 

Example

{
    "url": "https://app.yourserver.com/hooks-api/post",
    "method": "POST",
    "authentication": {
        "username": "jdoe",
        "password": "p@55w0rd"
    },
    "headers": {
        "Content-Type": "application/json"
    },
    "postData": {
        "title": "{{webhook_subject}}",
        "text": "{{webhook_body}}"
    }
}

Example using POST and 'multipart/form-data' payload

In some cases, the listening application may require data in an alternate format, such as 'multipart/form-data'.

Omnilert will convert the 'postData' items into the format specified in the 'Content-Type' setting as shown below.

Example

{
    "url": "https://webhook.site/cb2e8b18-d2a6-4e32-bc38-269af410b091",
    "method": "POST",
    "headers": {
         "Content-Type": "multipart/form-data"
         },
    "authentication": {
         "username": "jdoe",
         "password": "p@55w0rd"
          },
    "postData": {
         "title": "data-{{webhook_subject}}",
         "text": "data-{{webhook_body}}",
         "test": "data-hello world"
          }
} 

While the settings code here is JSON, the payload delivered via the HTTP POST from Omnilert will be sent as 'multipart/form-data'.

Also, note that you can mix hard-coded text and text variables together within the webhook 'postData' and 'params' section to get the desired result.

Bypass Service Status Check

As part of its startup routine, Omnilert attempts to check the availability of endpoints when loading the Send Message screen. This diagnostic feature lets the sending admin know if the receiving server is online and ready to receive a message when they are composing a new alert.

This "status check" works by sending a simple HTTP OPTIONS request to the URL for the listening server. The success/failure of the OPTIONS request determines whether a given endpoint shows a green or red circle when admins attempt to send an Omnilert message.

In some cases, the "Service Status" feature may be undesirable; the listening server may not allow OPTIONS requests, or such requests may cause problems on the receiving server. 

If you need/wish to prevent these status checks, simply check the "Bypass Service Status Check" box and then click Update Configuration. (Please note that Omnilert will not be able to scan your server for availability if the service status check is bypassed!)  

Specific guides for posting webhooks to services using Webhooks

• Sending Omnilert messages to a Slack channel
• Sending Omnilert messages to a Google Spaces channel