Webhook Push Notifications (v1.1)

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.

{
     "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 object) to be used for a single dispatch event within the notification message.

With these test endpoints you can simulate the different types of dispatches you could receive. Refer back to the Types of Events and Dispatch Event Processing sections of the Dispatch Automation guide for the various scenarios to test.

Example Payload For Trigger Test Notification Endpoints

{
  "meter_id": "dcd47bc4-211b-43cc-9a95-d881a3abcbf2",
  "timeslot": {
    "start_time": "2022-06-13T19:00:00Z",
    "end_time": "2022-06-13T20:00:00Z",
    "energy_kw": "175",
    "test_event": false,
    "market_type": "day-ahead",
    "cancelled": false,
    "programs": [
        "NYISO-SCR"
    ]
  }
}

🚧

Multiple Events

It is not currently possible to send 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 however both of these scenarios are possible with actual market/program dispatches.

📘

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 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 will retry any notifications that failed due to timeouts or non-2XX responses multiple times (with a delay in between each) before giving up.

📘

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 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 section of the Dispatch Automation guide.

Meter Notification Example

{
  "test_notification": true,
  "meter_dispatches": [
    {
      "meter_id": "dcd47bc4-211b-43cc-9a95-d881a3abcbf2",
      "timeslots": [
        {
          "start_time": "2022-06-13T19:34:00Z",
          "end_time": "2022-06-13T23:00:00Z",
          "test_event": false,
          "energy_kw": 1.5,
          "market_type": "hour-ahead",
          "cancelled": false,
          "programs": [
            "ERCOT-ERS"
          ]
        }
      ]
    }
  ]
}

Market Group Notification Example

{
  "test_notification": true,
  "meter_dispatches": [
    {
      "meter_ids": [
        "dcd47bc4-211b-43cc-9a95-d881a3abcbf2",
        "261ww30e-x41f-483a-b245-b2da23619949"
      ],
      "timeslots": [
        {
          "start_time": "2022-05-25T22:00:00Z",
          "end_time": "2022-05-25T23:00:00Z",
          "test_event": true,
          "energy_kw": 1000,
          "market_type": "day-ahead",
          "cancelled": false,
          "programs": [
            "DRAM"
          ]
        }
      ],
      "market_group_id": "b731a5f2-c6a4-48b3-b47d-d5017a039ae7"
    }
  ]
}