How webhooks work

Energy Coordination API utilizes webhooks to provide real-time event notifications, enabling seamless integration with your services. This document outlines how to securely set up and handle webhook notifications, including signature verification and error handling.

How Webhooks Work

Webhooks enable your systems to stay synchronized with the Energy Coordination API. When an event occurs, we will send a webhook notification as an HTTP POST request with a JSON payload to your specified webhook URL. This payload contains information about the event.

Although events can also be fetched via the /events endpoint, using webhooks for real-time notifications is more efficient than polling the endpoint.

Notification Types

The Energy Coordination API currently supports the following notification types:

• PriceCurveCreated: Sent when a new price curve is created.
• UserEligibilityUpdated: Sent when the eligibility of your users is updated.
• LocationLPCCreated: Sent when the eligibility of your users is updated.

More notification types will be added as the API evolves.

Security

We sign every notification we send out with a signature in the X-Payload-Signature header. This signature is an HMAC SHA256 hash of the request body encoded in Base64 using the webhook secret as a key. You can compute the signature yourself and compare it with ours to ensure the notification originates from the Energy Coordination API.

To verify the signature:

1. Compute the HMAC SHA256 hash of the incoming request body using your shared secret as the key.
2. Encode the hash in Base64.
3. Compare your computed signature with the signature in the X-Payload-Signature header.

Adding Webhooks

Follow these steps to configure webhooks with the Energy Coordination API and ensure your system is ready to receive real-time event notifications.

Important

Start testing in the sandbox environment to ensure everything works as expected before moving to production. All partners have default access to the sandbox environment and must be granted access to the production environment after testing.

The base URL for the sandbox environment is https://api.sandbox.voluespark.com/energy-coordination/v1. You can also test the endpoints through the Swagger UI.

Step 1: Setting Up Your Endpoint And Resources

Prepare an endpoint in your API to accept POST requests. This endpoint will receive webhook event notifications from the Energy Coordination API.

Webhook Implementation Guide Information about best practices when implementing a webhook and some example code.

When an event occurs, our API will send a notification to your endpoint. A 2XX response indicates successful delivery. Any other status codes will result in up to 3 retries with exponential backoff. After three unsuccessful attempts, no further delivery attempts will be made, but you can still fetch the event via the /events endpoint.

Ensure you have registered users, locations, and resources in the Energy Coordination API. These resources are required to receive notifications for events related to these resources. Follow the adding resources guide to create these resources if you need test data.

Tip

You can use the /simulation/partner endpoint to create random simulated data for users, locations, and resources. However, the better option for integration testing is to create users, locations, and resources that reflect data from your system. Doing so will also be helpful when you start implementing energy usage reports so you have a running start.

Step 2: Authorization

To register your webhook, ensure you have a valid API token with the necessary permissions. To authenticate your requests, you will use this token in the Authorization header as a JWT Bearer token. If you don’t have a client ID and secret, you can create those in Spark Studio.

Step 3: Registering Your Webhook

To register your webhook, make a POST request to the /webhooks endpoint.

Request Headers

• Content-Type: application/json
• Accept: application/json
• Authorization: Bearer YOUR_API_TOKEN

Request Body

Provide the following details in the JSON body of your request:

{
  "name": "Name of your webhook",
  "webhookSecret": "your webhook secret",
  "webhookUrl": "https://yourdomain.com/api/",
  "notificationTypes": ["PriceCurveCreated", "UserEligibilityUpdated"]
}

Description of the parameters:

• webhookUrl: The URL where you want to receive webhook notifications.
• notificationTypes: An array of event notification types you wish to subscribe to. It is up to you to handle all events with one webhook or create multiple webhooks to handle specific types.
• name: (Optional) A descriptive name for your webhook used in UI and debugging.
• webhookSecret: (Optional) A secret string for signature verification. The Energy Coordination API will use this to generate an HMAC SHA256 signature of the payload, providing an additional layer of security.

Sample cURL Command

curl -X POST "{{baseUrl}}/webhooks" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -d '{
           "name": "Handle PriceCurve created",
           "webhookUrl": "https://yourdomain.com/api/"",
           "notificationTypes": ["PriceCurveCreated"],
           "webhookSecret": "exaglIXHM6IZue0",
         }'

After registering your webhook, you will receive a 201 Created response with the webhook details.

Webhook Testing Now that you have set up your webhook, you can test event deliveries to ensure deserialization and signature validation works properly.