Dispatch 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. A 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 so that your event processing logic 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

🚧

Storing Leap Meter IDs a Prerequisite for Dispatch Automation

Unless you are managing a small number of meter IDs manually, you will need to integrate with the Meter Webhooks or Meter Enrollment API endpoint in order to complete dispatch automation. See the Ensure readiness for dispatch events section of the Sync Meter Inventory guide and review use case A (storing meter ID), use case B (tracking enrollment status), and optionally use case C (syncing market group mapping).

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 dispatches at the meter or market group level:

*Each group dispatch event notification will include both the group ID and the list of your meter IDs which are part of that group. The energy curtailment awarded (kW) should be distributed across this group of meters.

📘

Group Webhook Recommended (even for meter-level dispatching)

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.

❗️

Dispatching a Pre-Configured Portfolio of Assets

If your device management platform must dispatch in pre-configured groups, it is essential that you keep your internal groups in sync with Leap. Dispatching a group with outdated group assignments can cause poor dispatch performance and reduce grid services revenues.

See 'Use Case C' in the Sync Meter Updates guide for more details on automating these group updates.

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.

{
      "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 on a regular basis checking for new updates

📘

Webhook Push Recommended

The webhook approach is recommended over polling as it is most efficient and more easily enables participation in real-time markets. It also allows for sending yourself 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 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) in order to verify that everything is working properly and devices are responding.
  • This is supported for the webhook, dispatch API polling, and email notifications. Events are stored in the Leap dispatch database and will show up on the Dispatch Tab in the Portal and in the Dispatch API.
• Dispatch notification field: communication_test= true
  • Webhook example
  • Dispatch API example
• 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. If you do not want end customer devices to take action, these events can be cancelled after scheduling is confirmed. Cancelling these events allows for confirmation that the event was scheduled correctly but it does not confirm responsiveness of the devices.

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.
  • Only supported for webhook dispatch integrated partners. These test events are not stored by Leap.
• Dispatch notification field: integration_test_notification = true
  • Webhook example
• Partner action: Dependent on partner testing goals.