How to Integrate with the Gisual Power Outage Intelligence Webhook API

This article explains how to use Gisual’s Power Outage Intelligence Webhook API to search for power statuses.

Usage

When you request power status from the Intelligence Webhook API, Gisual begins a validation process for power status at the one or more locations in a single request.

The Gisual API responds to that request with an HTTP 202, meaning that the system has accepted your request for processing and is doing work.

No power outage information comes in the response, that information is exclusively sent from the Gisual system to your webhook endpoint.

The basic response body looks like this:

{
  "invalid_locations": [],
  "online_locations": []
}

If you integrate with Gisual by sending our team your asset database to load into your instance, you can send asset names instead of locations, and the Gisual system will look their locations up.

If you send an asset name that the system cannot find, you will see that asset name in the "invalid_locations" list, like so:

{
  "invalid_locations": ["Node PHL013.56"],
  "online_locations": []
}

You can also send the Gisual API a notification that an asset has come back online by setting the "asset_status" field in the request for that asset to "up". If you do that, the asset name will appear in the "online_locations" list, like so:

{
  "invalid_locations": [],
  "online_locations": ["Node PHL013.57"]
}

Once the Gisual system correlates a power outage for a location, your webhook endpoint will automatically receive the intel. The Gisual system will then track the outage, sending updates when the ETR changes, until the outage resolves, at which time one final notification will be sent.

Gisual's largest customers find this system very convenient, because a single request from your integration ensures you receive all updates over the lifecycle of all power outages without having to poll Gisual for information.

Power Status

Gisual will return the power status to your webhook endpoint. The possible values for power status are listed in the table below:

Status	Description
validating power	Gisual is performing initial validation to confirm power status at the requested location.
power on	Power is ON at the requested location and no outage was found.
power on - outage resolved	Power is ON at the requested location and the outage has been resolved.
power off	Power is OFF at the requested location.

Usage Lifecycle

Here is the life cycle for using the Gisual Power Outage Intelligence Webhook API.  

1. Query Gisual using one or more locations, for example physical addresses or a latitude/longitude pairs, or asset names if your asset database has been imported to your Gisual instance.

2. Ensure the HTTP response code is 202.

3. Ensure that no "invalid_locations" are returned if you are using asset names.

4. Wait for Gisual's system to send notifications to your webhook endpoint.