Webhook Push Notifications
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 themeter_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 betrue
for all notifications triggered by these test endpoints andfalse
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:
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 1 month ago