Alerts API

When an Event is generated for an Insight being monitored with Alert, the system will trigger out Webhooks Notifications. There are two types of potential trigger events:

Insight Categories (aka Severe Weather Events): monitor the issuance of weather hazards as reported by national authorities
Custom Insights: tailor conditions to your exact use-case, from our collection of >80 data points

Once your alerts are configured, make sure to set up a proper Alert Listeners on your application side, to handle these incoming events.

Notification Configuration

The notifications object is an array of objects as shown below; each containing the enum of the scheduling type, and two additional attributes - description and title` - that can be used to enrich the messages on the receiving webhook side (in addition to the event values).

Attributes	Description
`type` string: `PRIOR`, `START`, `END`, `PUBLISH`	The type of notification, whereas the enums follow `PRIOR`: sending notification before events where the Custom Insights are truthy `START`: sending notification at the start of events where the Custom Insights are truthy `END`: sending notification at the start of events where the Custom Insights are truthy (aka all-clear) `PUBLISH`: sending a notification as soon as weather hazards are issued by authorities, according to the respective Insight Category
`value` number	In case of `PRIOR` notification, defines the time (in minutes) before an event is forecasted to occur in which the system should send out a notification. In case of `END` notification, defines the time (in minutes) for “all clear duration” which will determine the amount of time for which conditions must be forecasted as unmet for the “all clear” alert to be sent.
`title` string	Additional descriptive attribute to be sent in the webhook.
`description` string	Additional descriptive attribute to be sent in the webhook.

[
  {"type": "PRIOR", "value": 30},
  {"type": "START"},
  {"type": "END", "value": 120}
]

[
  {"type": "PUBLISH"}
]

Lightning Configuration

The lightningConfig object is a JSON object as shown below; each containing the properties required to configure a new lightning alert.

Attributes	Description
`lightningTypes` array of strings: `C2C`, `C2G`	an array of possible lightning types based on which alert detection happens. Allowed values: C2C (cloud to cloud) and C2G (cloud to ground).
`buffers` array of ints	an array of radiuses based on which the alert detection happens (as soon as lightning strike occurs in one of the buffer, the alert notification is triggered). Minimum buffer value 0.6 and maximum value 48. Note that only first strike within the buffer triggers the alert notification.
`ttl` int	duration of all-clear notification since the last strike happen within the buffer
`distanceUnit` string: `km`, `mi`	the unit of buffer distance, allowed values km (kilometers) or mi (miles)

Lightning configuration object example:

"lightningConfig": {
    "lightningType": ["C2G", "C2C"],
    "buffers": [3, 5],
    "distanceUnit": "km",
    "ttl": 15
}

Webhook Payload

On the account level, you can configure a webhook and your own secret to which triggered events will send notifications (as defined per Alert).

Note the locations attribute in the payload should be used instead of the location attribute. The location attribute will be deprecated in the future. For Insight Alerts only one location will be provided in this attribute as the API does not send multiple locations for a single notification for Insight Alerts.

Payload objects:

Object	Description
`insight`	Details the insight ID or category for which this event is truthy.
`locations`	An array listing all location objects, each with a unique ID, in which this reported event occurs. Note that for alerts based on custom insights, this array will consist of a single location, while for insight categories it might consolidate alerts for multiple locations.
`alert`	Details the configuration of the alert, for which the notification was sent out - usually used for the enrichment of content by the distribution service.
`notification`	Details the specific notification configuration that triggers the webhook message - either `PRIOR`, `START`, `END` or `PUBLISH` type, each with optional `title` and `description`.
`event`	See full details below.

Event attributes:

Attribute	Description
`startTime` string (ISO 8601)	The time in which the event starts (sent with `PRIOR`, `START`, `PUBLISH` notifications)
`endTime` string (ISO 8601)	The time in which the event ends (sent with `END`, `PUBLISH` notification)
`eventValues` object	The parameter values for this event in the monitored location. In the case of alerts based on custom insights, these will be the values for all of the fields in the conditions tree. However, for category insights - please review the relevant full list event attributes
`triggerValues` object	The subset of parameter values that has made the conditions object to be truthy for the location (sent with `PRIOR`, `START`, `END` notifications - only custom insights)

Payload Example:
These are example payloads for the "Alerts" type of webhooks you can subscribe to. You can expect to receive a message with the same structure as these examples whenever you subscribe to the corresponding notification.

ℹ
Note
Some payloads will contain additional information as well, however, make sure to rely only on the attributes listed in the Custom Insights and Insight Categories sections.

{
    "data": {
        "alert": {
            ...alert
        },
        "insight": {
            "id": "38f689d83c264eb0b084ba095f2ea332"
        },
        "location": { // DEPRECATED
            "id": "38f689d83c264eb0b084ba39975f3413"
        },
        "locations": [
          { "id": "38f689d83c264eb0b084ba39975f3413" }, 
        ],         
        "notification": {
            "type": "PRIOR",
            "value": 30,
            "title": "Low Visibility Advisory",
            "description": "* WHAT... Visibility 1km or less * WHEN... in 30 minutes * IMPACTS... Hazardous driving conditions due to low visibility * ACTIONS... If driving, slow down, use your headlights, and leave plenty of distance ahead of you."
        },
        "event": {
            "startTime": "2020-05-10T07:49:34+0000",
            "eventValues": {
                "visibility": 0.52
            },
            "triggerValues": {
                "visibility": 0.52
            }
        }
    }
}

{
    "data": {
        "alert": {
            ...alert
        },
        "insight": {
            "id": "floods",
        },
        "location": { "id": "5ea83909b9dc140008627002" }, // DEPRECATED  
        "locations": [
          { "id": "5ea83909b9dc140008627002" }, 
          { "id": "5ea83909b9dc140008627003" }, 
          { "id": "5ea83909b9dc140008627004" },
        ],
        "notification": {
            "type": "PUBLISH",
            "title": "Flood Hazard",
            "description": "A flood hazard has been published. Review hazard details. "
        },
        "event": {
            "startTime": "2020-10-13T18:12:00Z",             
            "endTime": "2020-10-14T15:06:26.261668224Z",     
            "updateTime": "2020-10-13T18:12:00Z",            
            "severity": "unknown",                           
            "certainty": "likely",                         
            "urgency": "unknown",                            
            "source": "https://alerts.weather.gov/cap/...",  
            "eventValues": {
                  "origin": "NWS",                           
                  "title": "Small Craft Advisory",          
                  "description": "* WHAT...Northwest... ",   
                  "instruction": "Inexperienced... ",        
                  "response": "avoid",                       
                  "geocodes": ["PZZ576"],                    
                  "location": GEOJSON_GEOMETRY,              
                },
            }
        }
    }
}

Notification Configuration

Lightning Configuration

Webhook Payload

ℹNote

ℹ
Note