---
updatedAt: 2026-06-22T11:05:56.000Z
agentTools:
  projectIndex: https://docs.tomorrow.io/llms.txt
---

# Alerts API

When an **Event** is generated for an **Insight** being monitored with **Alert**, the system will trigger out [Webhooks](https://docs.tomorrow.io/reference/api-webhooks) **Notifications**.  There are two types of potential trigger events:

* [Insight Categories (aka Severe Weather Events)](https://docs.tomorrow.io/reference/insights-categories-overview): monitor the issuance of weather hazards as reported by national authorities
* [Custom Insights](https://docs.tomorrow.io/reference/insights-overview): 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](https://docs.tomorrow.io/reference/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).

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Attributes
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `type`

        string: `PRIOR`, `START`, `END`, `PUBLISH`
      </td>

      <td>
        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
      </td>
    </tr>

    <tr>
      <td>
        `value`

        number
      </td>

      <td>
        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.
      </td>
    </tr>

    <tr>
      <td>
        `title`

        string
      </td>

      <td>
        Additional descriptive attribute to be sent in the webhook.
      </td>
    </tr>

    <tr>
      <td>
        `description`

        string
      </td>

      <td>
        Additional descriptive attribute to be sent in the webhook.
      </td>
    </tr>
  </tbody>
</Table>

```json Custom Insight Notifications
[
  {"type": "PRIOR", "value": 30},
  {"type": "START"},
  {"type": "END", "value": 120}
]
```
```json Insight Category Notifications
[
  {"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.

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Attributes
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `lightningTypes`

        array of strings: `C2C`, `C2G`
      </td>

      <td>
        an array of possible lightning types based on which alert detection happens. Allowed values: C2C (cloud to cloud) and C2G (cloud to ground).
      </td>
    </tr>

    <tr>
      <td>
        `buffers`

        array of ints
      </td>

      <td>
        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.
      </td>
    </tr>

    <tr>
      <td>
        `ttl`

        int
      </td>

      <td>
        duration of all-clear notification since the last strike happen within the buffer
      </td>
    </tr>

    <tr>
      <td>
        `distanceUnit`

        string: `km`, `mi`
      </td>

      <td>
        the unit of buffer distance, allowed values km (kilometers) or mi (miles)
      </td>
    </tr>
  </tbody>
</Table>

Lightning configuration object example:

```json
"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).

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

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Object
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `insight`
      </td>

      <td>
        Details the insight ID or category for which this event is truthy.
      </td>
    </tr>

    <tr>
      <td>
        `locations`
      </td>

      <td>
        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.
      </td>
    </tr>

    <tr>
      <td>
        `alert`
      </td>

      <td>
        Details the configuration of the alert, for which the notification was sent out - usually used for the enrichment of content by the distribution service.
      </td>
    </tr>

    <tr>
      <td>
        `notification`
      </td>

      <td>
        Details the specific notification configuration that triggers the webhook message - either `PRIOR`, `START`, `END` or `PUBLISH` type, each with optional `title` and `description`.
      </td>
    </tr>

    <tr>
      <td>
        `event`
      </td>

      <td>
        See full details below.
      </td>
    </tr>
  </tbody>
</Table>

**Event attributes:**

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Attribute
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `startTime`

        string (ISO 8601)
      </td>

      <td>
        The time in which the event starts (sent with `PRIOR`, `START`, `PUBLISH` notifications)
      </td>
    </tr>

    <tr>
      <td>
        `endTime`

        string (ISO 8601)
      </td>

      <td>
        The time in which the event ends (sent with `END`, `PUBLISH` notification)
      </td>
    </tr>

    <tr>
      <td>
        `eventValues`

        object
      </td>

      <td>
        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](https://docs.tomorrow.io/reference/insights-categories-overview)
      </td>
    </tr>

    <tr>
      <td>
        `triggerValues`

        object
      </td>

      <td>
        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)
      </td>
    </tr>
  </tbody>
</Table>

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

<Callout icon="ℹ" theme="default">
  ### Note

  Some payloads will contain additional information as well, however, make sure to rely only on the attributes listed in the [Custom Insights](https://docs.tomorrow.io/reference/insights-overview) and [Insight Categories](https://docs.tomorrow.io/reference/insight-categories)  sections.
</Callout>

```json Custom Insight Payload
{
    "data": {
        "alert": {
            ...alert
        },
        "insight": {
            "id": "38f689d83c264eb0b084ba095f2ea332"
        },
        "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
            }
        }
    }
}
```
```json Sever Weather Event Payload
{
    "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,              
                },
            }
        }
    }
}
```