Triggers: API Triggers

Omnilert provides the ability to allow your external applications to launch Omnilert Scenarios directly via HTTPS requests via "API Triggers".   

To use this feature, you will need the following:

• An external service/server that can send HTTPS POST requests to Omnilert
• Omnilert service with access to the Triggers features
• Access to the Omnilert admin portal as a Super Admin user
• An Omnilert Scenario to launch when the trigger receives a request*

(*Just getting started? This walkthrough assumes that you're familiar with Omnilert's Scenarios feature. See Creating a Scenario [VIDEO] for the basics of creating a scenario and Actions: Adding an Action for instructions on creating new 'actions'. You'll need to create your scenario before you can complete this setup.)

 

Adding a new API trigger

Add a new trigger on the Scenarios Manager > Triggers and click  Add Trigger 

Select the "API" type for your trigger. Assign the trigger a name and (optional) description.

By default, new triggers are created as "Inactive" triggers. Select the "Add trigger and make active" option when saving your trigger to activate your trigger immediately.

Once added, your newly activated trigger will be listed in the "active" trigger list. You will need to view the trigger's details to continue. (See below)

 

API trigger information 

The details for your new API trigger will be located within the trigger details. Go to Scenarios Manager > Triggers. 

Your new trigger will be listed along with any other triggers in your Omnilert system. (By default, the list shows "active" triggers. If your trigger is "inactive", you may need to adjust the filter at the top of the list to find it.)

 

You will need to send your requests as HTTPS POST requests to a custom URL with a special "key" in the header of each request.

Click on your new trigger in the list to view its details screen:

There are two key pieces of information on this screen that you will need to use in your external application to configure your API requests:

• API key: This is the unique passcode for your trigger. It must be passed in your HTTPS requests' header as the 'value' for a 'key' called x-api-key
• Trigger URL: This is the custom URL for your trigger. This URL is where you will POST your requests to Omnilert.

Any HTTPS post to your custom trigger URL with the proper API key in its header will cause the linked scenario to launch. 

 

The Trigger name and Trigger description fields are the display name and descriptions seen within Omnilert's admin portal for this trigger. (Use a name and description that will help you remember what this trigger is being used for in the future.)

 

Linking a scenario to the trigger

You must select a Scenario to launch when the trigger receives a valid HTTPS POST request.

 

Note: If you haven't created a scenario already, please skip ahead and come back to this section after you've created your scenario!

 

Assuming that a scenario is set up and ready, link the desired scenario to your trigger as follows:

• To go Scenario Manager > Triggers > Active
• Click on the new API trigger.
• Then click the Scenarios tab within that trigger's detail info.
• Select a scenario from the list of active scenarios.
• Click Update trigger to save changes

 

The system will launch the linked scenario when Omnilert receives a valid API request (with the proper key) to your custom trigger URL via HTTPS POST.

 

 

Passing POST content to the Omnilert as variables

Triggers cause a scenario to launch when an event occurs. In this case, the "event" is a post to Omnilert from your external system. Naturally, Omnilert's Triggers need at least 1 scenario to launch when a triggering event occurs.

Assuming you have a scenario created, your scenario should have at least one valid 'action'. (Actions are the messages that send when a scenario is launched.)

That action will likely need to display some content from the triggering event.  Content is passed to Omnilert's scenarios using "variables". 

In this case, the variable is defined by the incoming POST request inside of its content. You can name the variable almost anything you'd like, so long as the same spelling/case is used within the requests and the actions in your scenario. 

 

An example app

For example, let's call our variable my-variable. We want to pass text content with this variable over to a scenario in Omnilert.

You will pass my-variable as part of the request (as form-data or in the JSON payload) in your API requests.

In this case, I want to pass a simple message of "This is a test message." to Omnilert as content-type: form-data.

Below we have a simple request set up in Postman (a testing tool used to send requests). 

The above request will send a POST request with my-variable = 'This is a test message.' as its body content, formatted as 'form-data'.

 

Inserting variables into a scenario action

In Omnilert, I have created a scenario "Action" to relay this variable's content in an outgoing message. Simply place the variable name inside curly braces {{like_this}}.

In our example, the variable name chosen was my-variable, so this variable is inserted into the Omnilert message as {{my-variable}}

When the scenario launches, {{my-variable}} will be replaced with the content from the incoming API request via HTTPS Post. 

In this example, the actual message relayed by Omnilert will look like the following:

 

As we can see, the message includes the text content from the API request ("This is a test message.")

Naturally, you can pass multiple variables to the Omnilert trigger and use them within your outgoing Omnilert scenario actions as you see fit.

So, if you need to pass more than one data item to your Omnilert messages, just assign each one a variable and include those in your scenario action accordingly. 

 

 

Notes and Tips

Rate Limit

The Omnilert API Trigger system has a rate limit of 1 API request per second. 

If you exceed the rate limit by sending too many requests, you will receive an HTTP error 429 (Too Many Requests) as a response. Please wait one minute before you try your request again.

 

PLEASE NOTE: Each request will cause Omnilert to launch a scenario, potentially sending large numbers of alert texts, emails, and app messages. To prevent abuse, repeated excessive requests (spamming) will result in the trigger being inactivated or otherwise removed from service.

 

HTTPS POST data content-type

Omnilert's trigger URL will accept HTTPS POST requests with data in the 'body' of the request. The following data formats are permitted:

• form-data
• x-www-form-urlencoded
• application/json (If raw, the data must be  ASCII text and JSON encoded)

 

HTTPS is required

For security, all posts must use HTTPS, not HTTP to secure data in transit.

 

Images and file attachments not supported

Note that you can only pass plain text (ASCII) to Omnilert triggers in the post body. Other data, such as images and files, is not permitted.