Using Active911's URL Integration (Webhook)

Due to changes in our County's dispatch system my fire department has begun using Active911 for phone-based dispatch and response. For the most part it has worked pretty well. There are a few issues, but their support has been responsive so I'm hopeful they'll all get sorted out eventually. For my part, I'm most excited that they offer both inbound API and outbound integration options.

At least I was excited about the integration options until I saw the documentation. It doesn't tell you basic things like what HTTP method will be used and what format the data will come in. When I asked Active911's support to answer these questions they told me they couldn't "disclose" the basic required information you'd need to use this feature. So I fired up ngrok and let it run for a while until it captured a few calls worth of data. This post is based on an email I sent to support with attached feature documentation in MediaWiki syntax with the hope that they'll post it on their site.

Once you log in to your Active911 in the Agency tab click 'New Integration'. You can see there are several pre-built integration options. I want the data to come to my app so select 'Other'. Give it a name and provide the URL you want contacted whenever a call comes in.

With that setup Active911 will make a POST request to your specified URL when a new alert is received.

Important to note is that you cannot trigger this webhook by creating your own alerts through the app or the web admin. It is only triggered via alerts that come from your dispatch system.

The Content-Type header is set to 'application/json' and the data is a valid JSON object that looks something like this:

{
 "agency": {
   "name": "Your agency's name",
   "id": 99999,
   "timezone": "America/Los_Angeles"
 },
 "alert": {
   "id": "999999999",
   "city": "Corvalis",
   "coordinate_source": "google",
   "cross_street": "",
   "description": "",
   "details": "Alert details and notes.",
   "lat": -123.296392,
   "lon": 44.550964,
   "map_address": "4100 SW Research Way",
   "map_code": "",
   "place": "",
   "priority": "",
   "received": "1570054351",
   "source": "",
   "state": "OR",
   "unit": "",
   "units": "11",
   "pagegroups": ["0"],
   "stamp": 1570054351.43062
   }
 }

Keep in mind that I'm inferring based on what I got from the few calls that I collected. I'm not sure what some of the fields mean, what the range of possible options is for some fields, or even if this the superset of all possible fields.

A few things that seem true to me:

• 'received' and 'stamp' are both Unix Epoch time stamps.

• 'alert':'id' is the same value that can be found for the alarm in the Active911 admin page under 'Details' as 'Active911 #'.

• 'pagegroups': The 'everyone' group has a value of "0".

• 'details' uses 'rn' for new lines.

There are still things I don't know for sure, but I'm sure Active911 knows and could fill in the gaps:

• Is 'unit' the unit number such as 'Apt B' or 'Unit 401'?

• What are the possible values for 'coordinate_source'?

• Is there a known set of values for 'priority' or is that agency/dispatch center specific?

• Is there a known set of values for 'source'?

• Is the array of 'pagegroups' always a string of integers represented as strings or will there be strings as well?

• Are there other fields that might be included based on type of call or dispatch information?

• Basically every field with an empty value I didn't get data for, so it isn't always clear what the field represents or what data might be included.

I plan to use the webook integration to trigger my app to query their API when we receive calls. The API appears to be much better documented, so I expect that part to go smoothly.

When Active911 updates their docs I'll update this post to link to the official docs. In the meantime hopefully this will be helpful to someone.