Webhooks

If your integration needs to execute actions in response to something happening within the ev.energy system, you can use webhooks to receive notifications of those events rather than having to constantly poll for changes.

To find out about the events we currently support, click here.

The data field of every webhook event contains the resource in exactly the same representation you receive via API calls for the same resource, allowing you to use the same code to handle both.

The body of a webhook request is a JSON envelope with three fields:

• type — the event type that occurred (for example, charging_sub_session.created or charging_sub_session.ended). The same value is also delivered in the svix-event-type request header, so you can route on the header without parsing the body.
• timestamp — an ISO 8601 UTC timestamp for when the event occurred (for example, 2022-11-03T20:26:10.344522Z).
• data — the resource itself, in exactly the same format you would receive from the equivalent API endpoint (for example, a charging_sub_session.created event carries the same representation as GET /v2/charging_sub_sessions/{id}).

Note that the envelope's timestamp (when the event occurred) is distinct from the svix-timestamp delivery header (when the message was dispatched).

Each request also includes the standard Svix delivery headers:

• svix-id — a unique identifier for the message that stays stable across delivery retries, so you can use it to deduplicate events.
• svix-timestamp — the time the message was dispatched, as a Unix epoch timestamp in seconds.
• svix-signature — a space-separated list of HMAC signatures (multiple may be present during key rotation) you should use to verify that the request genuinely came from ev.energy and was not tampered with. See the Svix guide to verifying payloads for how to do this.

Webhooks can be configured via the Webhook Portal, which is accessed via a unique generated link for your application. To generate the link, make an authenticated request to the Webhook Portal endpoint. The response will contain a link you can open in a web browser to access the portal.

For more information about how to use the portal, please consult the documentation for Svix, the platform which powers our webhooks.

It is important to remember that webhooks are a fundamentally unreliable mechanism. We will automatically retry failed event messages, and you can manually replay messages that have failed via the portal. However, given the possibility of errors or downtime for our systems, your systems or third parties between us, we can never 100% guarantee that all webhook events will be delivered successfully. You should always have a fallback system which can pull data via direct API requests.