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 themeter_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 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 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"
}
]
}
Updated about 1 year ago