Developer Guides

Webhook Push Notifications

Suggest Edits

This guide takes you through the steps and considerations when setting up dispatch event push notifications from Leap to your webhook endpoint. Leveraging this webhook push method is recommended in order to get dispatch notifications as soon as they become available, enabling participation in real-time programs that provide minimal advance notice periods.

1. Setup Your Webhook Endpoint

This webhook endpoint should be reachable on the Internet and accept HTTPS POST requests from Leap on port 443. If you don't yet have an external URL for your endpoint, you can use a free tool like webhook.site or Mockbin for testing.

2. Set Your Webhook URL in Leap

Use the meter-level set webhook URL endpoint or group-level set group webhook URL endpoint to configure the URL that Leap will use to post dispatch notifications to.

🚧

Webhook Security

It is recommended to include an API key or authentication token as part of the headers array so that your endpoint can use this to validate these incoming requests from Leap.

Note: all header names will be sent in lower case text regardless of how they were configured in this headers array.

{
     "headers": [
          {
               "name": "x-api-key",
               "value": "your-test-key"
          }
     ],
     "url": "https://webhook.site/4a0a9a89-d571-4ab7-ae8c-f5c864a3e5d1"
}

3. Send Your Endpoint a Test Notification

You can use the provided trigger test notification endpoints (meter-level | group-level) to send your webhook endpoint a test notification. These test endpoints allow you to define all of the values (meter/group IDs and timeslot objects) to be used for dispatch events within a notification message. Review the tables within the Dispatch Event & Program Prioritization guide for the priority, performance_compensation_cap, and is_voluntary values for each program you would like to setup test events for.

With these test endpoints you can simulate the different types of dispatches you could receive. Review the Test Cases guide for the different scenarios to test.

🚧

Multiple Events

With these test notification endpoints, it is possible to send yourself test notifications with more than one timeslot within the timeslots array or more than one meter/group ID-to-timeslots combination within the meter_dispatches array as could happen with a real market/program event. See the push notifications shown at the bottom of this guide for an example of this.

📘

Notification Infrastructure

These trigger test notification endpoints use the same service and infrastructure (e.g. source IPs) as actual market/program events. The only difference is the integration_test_notification flag in the post body being set to true, indicating that it was initiated through one of these test endpoints.

4. Process Incoming Notifications

The Leap service sending the push notifications is expecting a 2XX HTTP response back for it to be considered a successfully delivered notification. The service currently retries any notifications that failed due to timeouts or non-2XX responses every 1 minute (for up to 50 minutes).

📘

Endpoint Monitoring

Setting up monitoring/alerting is recommended in order to ensure your webhook endpoint remains up and available as well as to check for any non-2XX responses back to Leap.

Webhook Processing Considerations:

  • Each webhook push notification includes a integration_test_notification field. This will be true for all notifications triggered by these test endpoints and false for all real dispatch notifications.
  • If your system successfully receives the notification but the acknowledgement response back to Leap gets dropped and the request times out, the two sides could be out of sync causing Leap to retry with another push notification which your system will consider a duplicate of the previous. Ensure your implementation can handle this corner case gracefully.

For additional processing considerations refer back to the Dispatch Event Processing and Dispatch Strategies sections of the Dispatch Automation guide.

Example Code Recipe

Check out the following example code recipe for processing these webhook push notifications:

🦉
Process dispatch events from meter-level webhook
Open Recipe

Meter Notification Example

{
  "integration_test_notification": true,
  "communication_test": false,
  "meter_dispatches": [
    {
      "meter_id": "dd21c76c-7126-4ef7-b0a6-f190fad300b2",
      "timeslots": [
        {
          "meter_event_id": "11cfced0-16f4-4fb7-b72e-5ff939ae541e",
          "start_time": "2023-06-05T00:00:00Z",
          "end_time": "2023-06-05T01:00:00Z",
          "cancelled": false,
          "performance_compensation_cap": "up-to-site-load",
          "priority": 1,
          "is_voluntary": false,
          "dispatch_event_types": [
            "day-ahead",
            "capacity-test"
          ],
          "programs": [
            "DRAM"
          ],
          "energy_kw": 10.000
        },
        {
          "meter_event_id": "22cfced0-16f4-4fb7-b72e-5ff939ae541e",
          "start_time": "2023-06-05T01:00:00Z",
          "end_time": "2023-06-05T02:00:00Z",
          "cancelled": false,
          "performance_compensation_cap": "up-to-site-load",
          "priority": 1,
          "is_voluntary": false,
          "dispatch_event_types": [
            "day-ahead",
            "capacity-test"
          ],
          "programs": [
            "DRAM"
          ],
          "energy_kw": 20.000
        }
      ]
    },
    {
      "meter_id": "dd21c76c-7126-4ef7-b0a6-f190fad300b2",
      "timeslots": [
        {
          "meter_event_id": "33cfced0-16f4-4fb7-b72e-5ff939ae541e",
          "start_time": "2023-06-05T01:00:00Z",
          "end_time": "2023-06-05T05:00:00Z",
          "cancelled": false,
          "performance_compensation_cap": "grid-exports-allowed",
          "priority": 3,
          "is_voluntary": true,
          "dispatch_event_types": [
            "standard"
          ],
          "programs": [
            "ELRP"
          ],
          "energy_kw": null
        }
      ]
    }
  ]
}

Market Group Notification Example

{
  "integration_test_notification": true,
  "communication_test": false,
  "group_dispatches": [
    {
      "market_group_id": "11aa7aae-24e5-455f-91e9-e0f5f145f2ae",
      "meter_ids": [
        "abae2779-e392-4f00-b0cf-32e716204f78",
        "bbae2779-e392-4f00-b0cf-32e716204f78"
      ],
      "timeslots": [
        {
          "market_group_event_id": "114751e8-c0df-4d69-8a4f-9e7cebef1f84",
          "start_time": "2023-06-04T23:00:00Z",
          "end_time": "2023-06-05T00:00:00Z",
          "cancelled": false,
          "performance_compensation_cap": "up-to-site-load",
          "priority": 2,
          "is_voluntary": false,
          "dispatch_event_types": [
            "day-ahead"
          ],
          "programs": [
            "DRAM"
          ],
          "energy_kw": 8.000
        },
        {
          "market_group_event_id": "224751e8-c0df-4d69-8a4f-9e7cebef1f84",
          "start_time": "2023-06-05T00:00:00Z",
          "end_time": "2023-06-05T03:00:00Z",
          "cancelled": false,
          "performance_compensation_cap": "grid-exports-allowed",
          "priority": 3,
          "is_voluntary": true,
          "dispatch_event_types": [
            "standard"
          ],
          "programs": [
            "ELRP"
          ],
          "energy_kw": null
        }
      ]
    },
    {
      "market_group_id": "331a7aae-24e5-455f-91e9-e0f5f145f2ae",
      "meter_ids": [
        "ccae2779-e392-4f00-b0cf-32e716204f78",
        "ddae2779-e392-4f00-b0cf-32e716204f78"
      ],
      "timeslots": [
        {
          "market_group_event_id": "334751e8-c0df-4d69-8a4f-9e7cebef1f84",
          "start_time": "2023-06-05T00:00:00Z",
          "end_time": "2023-06-05T04:00:00Z",
          "cancelled": false,
          "performance_compensation_cap": "up-to-site-load",
          "priority": 2,
          "is_voluntary": false,
          "dispatch_event_types": [
            "hour-ahead",
            "day-ahead",
            "capacity-test"
          ],
          "programs": [
            "CCA"
          ],
          "energy_kw": 12.000
        }
      ]
    }
  ]
}

Updated about 2 months ago