Account & basic events
Webhooks are configured at the account level. Once set up, they will transmit event notifications for the current account and all its subordinate (child) accounts. The account can be created directly on XENON.
Subscribing to events
To learn how to subscribe to events, please refer to the company wide webhook notification post. Our dedicated documentation, located under the Event section, lists a standard subset of events, plus additional events specific to cloud-connected EVs. These cloud-connector-specific events function exactly like any other company-wide notification and can be subscribed to using the same process.
We plan to integrate our event documentation with the upstream company documentation so they can be viewed as a single source; however, until that integration is complete, please refer to our documentation for a comprehensive list of all Cloud-Connector related events.
Commissioning an EV
First you can create create a system if you don’t have one. Be sure to an complete address and not latitude longitude. We control the EV only when it’s on the address specified on the system.
Second you must know the gateway ID of the cloud client used to reach the EV. If you do not have this information, it will be provided to you by us. Then you call the link endpoint to get access the EV and add the asset to the system.
It will provide a linkUrl the user can open and follow to connect an EV to gridx. At the end it will redirect the user back to the redirectURI provided in the request.
If everything worked as expected, you will receive an appliance create event. Adding If the EV is going to be controlled by ToU, you need to set the tariffs.
Off boarding an EV
If the user won’t use this system anymore, deleting the system is recommended. This action will automatically remove the EV asset, revoke the control permissions granted by the user, and clean up all associated resources.
If only the EV is to be removed call the unlink endpoint. This specific action will clean up all resources associated only with that EV asset (including charge configurations and sessions) and revoke our permission to control the EV, while leaving the parent system intact.
Showing EV state and charge sessions to users
You can use get the last measurements to show the user the current status of the EV.
Ideally you should query this endpoint only when the user have the app open on the screen that shows the EV current SOC, and then poll this endpoint once per minute. In order to show the charge sessions to the user, one could query the charge session endpoint.
None of those endpoint should be polled instead you should listen to EV events and only then query for new information or use the information provided by the event.
Notifying states to users
In order to notify an user that a charging session started or stopped, subscribe to the events charge started, charge stopped and charge failed.
In order to notify the user that the EV was plugged or unplugged, subscribe to the events EV plugged and EV unplugged.
Setting up charge mode
In order to charge the EV immediately once it’s plugged, set the charge mode FORCED_EV, where you can specify a minimum desired SOC, it will assume 100% when omitted.
In order to charge the EV using ToU or flex optimization, set the charge mode to DEPARTURE_TIME_EV, where you can define the minimum SoC at departure time, and the departure time that can be defined on a absolute timestamp (departureAt) or as a time of the day (departureDailyAt), so everyday when plugged the charge will be optimized to reach the desired SoC at the same time of the day.
The EV will be controlled by gridX only when it’s plugged and at home, where home location is set on the system.
Handling user actions
The user actions endpoint returns a list of required user actions for a given system. These actions represent tasks that users need to complete to unblock certain capabilities, such as accepting vendor terms and conditions or completing authentication steps.
Whenever there’s a new action the user has to do a new system/action event will be triggered.