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

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"}
]

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