Webhooks / Push API

GreenFlux supports both Pull and Push (WebHook) models.

We support Push for:

  • CDR
  • Session
  • Locations
  • ChargeStation Notifications

Detailed information on the response examples is provided in the guides and API reference.

📘

GreenFlux implementation of Push/Webhooks

Our basis for Push messages is how OCPI defines Push messages.

Webhooks need to be setup by GreenFlux Operations, external Customers can't directly subscribe.

Format and Authorization are strictly limited to OCPI setup and not customizable.

Use cases for webhooks

Below is a schematic overview of the different CPO APIs. Click on Image to enlarge.

4183




Session

  • At the start of a charging session, a PUT session request is sent
  • Once an updated MeterValue from the Charge Station is received, a PATCH update request is sent
  • Once completed, a final PATCH request is sent.

Locations

  • When a new location is created, a PUT request is sent.
  • Upon starting a charging session, the EVSE status is changed from AVAILABLE to CHARGING
    (or unrelated to Charging it could go to a faulted state)
  • Once completed, the EVSE is updated as AVAILABLE again

CDR

  • When the CDR is calculated, it is sent as POST

ChargeStation Status Notifications

  • Upon every status update, a PUT update is sent.

MeterValue

  • For completeness, MeterValues are not pushed or available via Webhook. A history of MeterValues can be retrieved via PULL requests.

🚧

No Retries

GreenFlux does not have a retry mechanism, it is a 'fire and forget'. We recommend implementing a Get call at the end of the day to check for missing updates on e.g. CDRs, Locations etc.

Setting up webhooks / push API

Endpoint format for Push requests

For Push requests, GreenFlux requires endpoints for each module to be setup (CDR, Session, Location etc.)
example:

  • your-company-url.com/cdrs
  • your-company-url.com/locations
  • your-company-url.com/sessions
  • your-company-url.com/notifications

Note: the target URL may be different per module.

For Session and Location endpoints, GreenFlux will attach the {country-code}, {party-id} and {object-id} at the end. For Patch Location, the {evse-id} is added at the end

Example:

  • Patch Session: your-company-url.com/sessions/NL/GFX/NLGFX63759510021327674-7f844
  • Patch Location: your-company-url.com/locations/NL/GFX/f24214df-6c8a-4236-b217-82ec52291e803/BE-BEC-E041503001-1

For CDRs, there is no further information attached to the end.

For ChargeStationNotifications, the ID is attached to the end:

  • your-company-url.com/{endpoint}/0cbfb073-2c9a-4cc0-819a-afe60be36088

For more detail, please look at the Guides for each of these modules.

Response status for Push messages

We recommend to implement the OCPI response format
See section 4.1.6 and section 5 for list of error codes: https://evroaming.org/app/uploads/2020/06/OCPI-2.2-d2.pdf

}
"status_code": 1000,
 "status_message": "Success",
 "timestamp": "2021-06-30T21:59:59Z"
}

Authorization

For GreenFlux to push to Customer’s platform, we require an authorization Token.
GreenFlux Push messages will include an 'Authorization' header and use 'Token' as Key.

The header looks as follows:

Authorization: Token IpbJOXxkxOAuKR92z0nEcmVF3Qw09GG7I7d/WCg0koM=

🚧

Authorisation methods

Currently we only support the above Authorisation method.

Example request to setup webhook/push messages

Dear GreenFlux, 

please setup a webhook for the modules CDRs and Locations for the following endpoints:

https://api.mycpocompany.com/external/cpo/locations
https://api.mycpocompany.com/external/cpo/cdrs

I will send the Authorization token via a secure data transfer to you.
// for example 'IpbJOXxkxOAuKR92z0nEcmVF3Qw09GG7I7d/WCg0koM='

Kind regards,
John Smith

For secure data transfer, use e.g https://onetimesecret.com/ and send in a separate email.

Checklist for setting up Webhooks

  • setup receiving endpoints (Action: Customer)
  • share endpoints and Authorization token with your GreenFlux CSM for GreenFlux to configure (Action: Customer & GreenFlux)
  • testing (Action: joint)

FAQ

Whitelisting

Please request information on our IP addresses in case you wish to whitelisting incoming requests

Bespoke Headers

Currently GreenFlux only support the Authorization headers as described above.

Custom or bespoke headers may be reviewed in the future.

Update Webhooks by Customers

Customers can't update the Webhooks by themselves, e.g. change the URL, Module or Authorization Token. Any change requests must go through a GreenFlux CSM.