Overview

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:

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).

AttributesDescription
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.

AttributesDescription
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:

ObjectDescription
insightDetails the insight ID or category for which this event is truthy.
locationsAn 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.
alertDetails the configuration of the alert, for which the notification was sent out - usually used for the enrichment of content by the distribution service.
notificationDetails the specific notification configuration that triggers the webhook message - either PRIOR, START, END or PUBLISH type, each with optional title and description.
eventSee full details below.

Event attributes:

AttributeDescription
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,              
                },
            }
        }
    }
}