Endpoints: Webhooks

Omnilert provides the ability to post alerts as "Webhooks" messages. Webhooks are user-defined HTTP callbacks* which 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 can then receive and process the message in any number of custom applications; including scrolling displays, website tickers, beacons, etc. 

The Webhooks endpoint configuration is quite simple:

• URL to post to: This is the URL of your listening server. Omnilert will POST messages in Webhook format to that URL.
• Username and Password: (Optional) If your server requires authentication*, enter the username and password used to authenticate.
• JSON output: (Optional) The message content can be sent in the popular JSON format. If unchecked, the POST will be made as Multipart/Form-Data.

The request will include the subject and message content from the outgoing Omnilert message as separate fields.

Basic Authentication

Omnilert's Webhook endpoint supports HTTP Basic Authentication. If your local application requires/supports authentication using this method, simply enter the username and password in the spaces provided.

Webhook Data formats:

There are two options for Webhooks message formatting from Omnilert:

• JSON encoded content.
• Multipart/Form-Data (text) format

JSON Format:

JSON is a popular formatting used for application data in many AJAX applications. (Read more at https://en.wikipedia.org/wiki/JSON)

An Omnilert webhook message in JSON formatting might look like the following:

{"subject":"Quick Test","message":"This is a test message body.","html_message":""}

As you can see, the key fields are presented as "subject" and "message" within the JSON structure. Your application would need to parse the JSON content and use those fields.

Multipart/Form-Data Format:

When delivered without JSON formatting, the POST will be made as a "Multipart/Form-Data" post, much like an HTML <FORM> post, with "subject" and "message" being the two form fields posted through the form.

Which should you use?

Of course, the format to choose is entirely dependent on your receiving application.  Most newer applications tend to use JSON formatting. However, if your developer wants to receive content as if it were a simple web form, then disable JSON.

Service Status Check

When saving the settings for Webhook, the system will send an empty message to the webhook listener URL listed in the Webhook settings. This listener server must respond with HTTP 200 "OK". (An error response will fail the check.)

Additionally, whenever the Send Message and/or Endpoints page loads, the system's service status check feature will send an empty request to the webhook URL. The Listening server should respond 200 - OK.

A successful check will result in a green disc. A failed check will display a red circle, indicating a communication problem with that endpoint.

* More info about Webhooks is available at https://en.wikipedia.org/wiki/Webhook