Dispatches Overview

Dispatches are signals from the Leap platform about a grid event. These dispatch events are requests for a meter or group of meters to curtail (or export in some cases) energy during a defined time period. A Leap dispatch notification could contain one or many of these unique dispatch events within it.

Responding to dispatches in a timely and consistent manner is essential to achieving high performance during grid events and maximizing revenue. An important part of this is automating the process of receiving and scheduling events so your customer's devices take appropriate action at the right time.

Leap's webhooks and APIs enable you to integrate once and scale to all available markets and programs. While there may be some nuances between programs, Leap simplifies the integration by providing a common dispatch notification structure that can be program-agnostic and leveraged across all markets and programs.

This guide provides an overview of the following (see the Dispatch Event Processing guide for implementation details and recommendations):

• Notification Structure
• Notification Methods
• Endpoints
• Types of Test Events

Notification Structure

A dispatch has two top-level components:

• Recipient: The Meter or Group responsible for responding to the dispatch event.
• Timeslot(s): The dispatch time period as well as additional details about the service required during that time period.

Recipient (Meter or Market Group)

You can choose to receive event notifications at the meter or market group level:

For efficiency reasons, most partners subscribe to the group dispatch webhook (to reduce the total number and size of push notifications) but then ignore the market_group_id and simply parse the array of meter_ids to see which meters were dispatched for a given event.

Timeslots

A timeslot describes the details of a dispatch. It includes the start and end time, energy quantity, and other event metadata. Additional details on these fields can be found later in this guide. See the Dispatch Event Processing guide for guidance on parsing these timeslot objects.

JSON Structure Example

{
  "meter_id": "afce893d-ea68-487f-9f8c-778b1881f60a",
  "timeslots": [
    {
      "meter_event_id": "f4cfced0-16f4-4fb7-b72e-5ff939ae541e",
      "start_time": "2022-06-02T00:00:00Z",
      "end_time": "2022-06-02T01:00:00Z",
      "cancelled": false,
      "energy_kw": 4.000,
      "nomination_kw": 4.000,
      "performance_compensation_cap": "up-to-site-load",
      "priority": 2,
      "is_voluntary": false,
      "dispatch_event_types": [
        "day-ahead",
        "capacity-test"
      ],
      "programs": [
         "CCA"
      ]
    }
  ]
}

Notification Methods

There are multiple options for receiving these dispatch notifications. The Leap API provides both push and pull models below:

• Webhook Push Notifications - Leap pushes notifications to your webhook endpoint as soon as they are available.
• Dispatch Event Polling - You poll the relevant Leap dispatch endpoint regularly checking for new updates.

The webhook approach is recommended over polling as it is most efficient and enables participation in real-time markets. It also allows for sending test dispatch events whenever you want in Production or Staging with any event payload, making it easier to test your integration.

Endpoints

The endpoints available to support these two methods are summarized below:

• Webhook Push - Meter-Level Push & Group-Level Push
  • Get/Set/Delete your webhook URL.
  • Trigger test notification to your webhook URL.
• Event Polling
  • Search Meter-Level Dispatches - For retrieving dispatch events broken out at an individual meter/site level.
  • Search Group Dispatches - For retrieving dispatch events by groups of aggregated meters/sites.

Types of Test Events

To avoid confusion, this section describes 3 different types of "test" events. Capacity Tests are real market/program events and should be treated as such. Communication and Integration test events are partner-initiated events for testing integration and dispatch readiness of customer assets.

Capacity Test

• Scheduled by: Leap or program operator during the program season based on program requirements.
  • This is a real event that impacts revenue. This is NOT a test event like the Communication Test or Integration Test events below.
• Dispatch notification field: capacity-test within the dispatch_event_types array of timeslots object.
• Partner action: This should be treated as a high-priority event that should be responded to in order to prove capacity to the market. Capacity performance will be used in settlement calculations.

Communication Test

• Scheduled by: Partner on Dispatch Tab in Partner Portal.
  • This is meant to be run by operations teams whenever something changes in the end-to-end integration setup (e.g., integration update, control system or customer device software upgrades) or whenever a new season starts (for programs that do not run year-round) to verify that everything is working properly and devices are responding.
• Dispatch notification field: communication_test= true
• Partner action: Leap recommends that partners process these communication test events just like real dispatch events so the end-to-end flow can be tested.

Integration Test

• Scheduled by: Partner via trigger test notification endpoint.
  • This is meant to be run by technical teams when making updates to the Leap dispatch integration or downstream systems.
• Dispatch notification field: integration_test_notification = true

Updated about 2 months ago.