Skip to content

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.

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.

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.

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

Terminal window
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.