External Events API

• Top-Level
• Events

1.0 Introduction

This document describes a REST API within ICON Signals to receive and process event messages from external systems.

Messages are sent as HTTP(S) requests to an endpoint on the Signals server.

POST requests can be sent for content types:

• application/json (recommended)
• application/ x-www-form-urlencoded

GET requests can be sent for very simple message payloads when no API keys are configured. This document will focus on POST requests.

2.0 API Endpoint and Authentication

For an ICON Signals server on an internal network, the REST Endpoint is

• http://{server address}:6502/api/evt/data

For Signals servers accessed via a reverse proxy, the Endpoint is usually

• https://{server address}/sr/api/evt/data

Basic authentication is supported. The username is always apikey and the password is an API key assigned by ICON Voice Networks for the site and application.

API keys are configured for an ICON Signals server in the Admin > Configuration > Environment page. Keys consist of between 6 and 32 alphanumeric, hyphen, period and underscore characters. Multiple keys can be configured if they are separated by commas and/or semicolons.

3.0 Message Payload

As mentioned in Section 1, Signals supports POST requests with a content type of application/ x-www-form-urlencoded, but application/json is strongly recommended. This document only covers JSON-format data payloads.

Signals parameters in the External Event (XE) message payload are detailed in the table below. All property names and values are case-sensitive.

An example generic curl-based request follows. The API key value is XYZ.686609E6.

curl -X POST --user 'apikey:XYZ.686609E6' \
  http://localhost:6502/api/evt/data \
  -H "Content-Type: application/json" \
  -d '{ "sigSrc": "XYZ",
        "sigType": "LOCKDOWN",
        "sigMode": "ACTUAL",
        "sigChanID": "Mayberry Elementary / Main Bldg",
        "sigMsg": "This is an alert message!"
      }'

Here is an example curl request that more closely resembles a message arriving from a non-ICON production external system.

curl -X POST --user 'apikey:Secur1.54AD2472' \
  http://10.129.0.154:6502/api/evt/data \
  -H "Content-Type: application/json" \
  -d '{ "sigSrc": "Secur1",
        "eventType": "alert",
        "eventCode": 1,
        "eventDesc": "Active Shooter Lockdown",
        "msg": "This is Mayberry Elementary School located at 315 Culbert St, Mt Airy, NC 27030. We have initiated a lockdown and need immediate assistance.",
        "location": {
          "name": "Mayberry Elem/Mt Airy",
          "street": "315 Culbert St",
          "city": "Mt Airy",
          "state": "NC",
          "zip": "27030"
        },
        "sender": {
          "userId": "121212",
          "employeeId": "111222",
          "firstname": "Jane",
          "lastname": "Smith",
          "title": "Principal",
          "email": "jsmith@mayberry.edu",
          "mobile": "5445551234"
        },
        "timestamp": "2022-01-09T20:42:244Z"
      }'

In this case, the eventCode parameter from the external system message will be used to determine the signal type (LOCKDOWN, EVACUATE, CLEAR, etc.).

The name property in the location object is used as the ID component of the signal name for the event raised in ICON Signals. When the message is received, ICON Signals raises the signal:

XE-Secur1-LOCKDOWN-ACTUAL-%Mayberry Elem/Mt Airy%

which is matched against a rule which sends a Rainbow notification.

The basic idea of the sig property names is that external system engineers can easily add them to existing POST requests with minimal chance of conflict.

The sigSrc property is required. It allows ICON Signals to identify which external system is sending the event message.

All other properties are technically optional within the specification.

ICON Signals | 2018-2022 ICON Voice Networks