Event Types

The following are a list of the event types currently implemented on the platform

meter_data.received
hosted_consent.approved
hosted_consent.revoked
api_keys.rotated
meter.created
customer.created

meter_data.received

This is triggered when any of your meters receive new data. This is particularly useful for meters that receive data at different times of the day (for residential meters in the UK for example). This is also useful when there are gaps in data, and our retry mechanisms try to fill those gaps over the subsequent hours.

meter_data.received notification has the following schema

{
  "subscription_id": "0315r6h8-7b9c-4b2e-bf8d-1139196ty78i",
  "event_id": "meter_data.received",
  "event_timestamp": "2024-04-28T11:44:01.010Z",
  "delivery_id": "ff1a1q3e-7a08-41f0-99e4-5bc1ce4e5t7u",
  "payload": [
    {
      "meter_id": "5rgh7884a9c14daf2a8u7f4e",
      "start_interval": "2024-04-27T00:30:00.000Z",
      "end_interval": "2024-04-28T00:00:00.000Z"
    },
     {
      "meter_id": "ft6yh890a9c14dafc5tb78k0", //different to the above meter_id
      "start_interval": "2024-04-25T00:30:00.000Z",
      "end_interval": "2024-04-25T00:10:00.000Z"
    },
     {
      "meter_id": "ft6yh890a9c14dafc5tb78k0", //same as the above meter_id but different interval
      "start_interval": "2024-04-26T00:30:00.000Z",
      "end_interval": "2024-04-27T00:00:00.000Z"
    }
  ]
}

This payload contains an array of meter interval updates. Because the payload may contain many different meters, and each interval may not be the same, it's important to treat each object in the array separately.

A recommended flow is to call the /v1/interval-data end point for each object in the array and retrieve the new data for that meter and interval. An example of this can be seen in the following recipe

↗️

Create a webhook endpoint when new data is available for meters

Open Recipe

hosted_consent.approved

Triggered when a customer approves a hosted consent request. This will probably be one of the more used webhooks in your system along with the meter_data.received. Depending on how your application is set up, your customer may either be on session or off session when granting consent to a meter. If on session then they will redirect back to your application using the redirect_url. However, for off session consent flows, you will need to implement a webhook to listen out for this approval.

A typical flow following the receipt of this webhook would be to automatically create a meter with this meter_number and hosted_consent_id

hosted_consent.approved notification has the following schema

{
  "subscription_id": "0315r6h8-7b9c-4b2e-bf8d-1139196ty78i",
  "event_id": "hosted_consent.approved",
  "event_timestamp": "2024-04-28T11:44:01.010Z",
  "delivery_id": "ff1a1q3e-7a08-41f0-99e4-5bc1ce4e5t7u",
  "payload": [
    {
      "hosted_consent_id": "5rgh7884a9c14daf2a8u7f4e",
    }
  ]
}

hosted_consent.revoked

End customers will always have the option to revoke consent of any meter they control. If consent is revoked, then the hosted_consent object will move to an invalid state and data will stop being collected for this meter. When this happens, the platform will create the hosted_consent.revoked event. Listening in for this event will ensure you are aware of actions taken by your end customer and are in a position to take corrective action

hosted_consent.revoked notification has the following schema

{
  "id": "6630f047feb1f65bad24870a",
  "account": {
    "id": "65c361949ecb86c35d5ef1c0",
    "name": "Account Name",
    "logo": "https://www.starkindustries.com/logo.png"
  },
  "customer": {
    "id": "65c361e09ecb86c35d5ef1c5",
    "account": "65c361949ecb86c35d5ef1c0",
    "name": "Customer Name",
    "email": "[email protected]",
    "address": "Fool's Lane 1",
    "logo_url": "https://www.starkindustries.com/logo.png",
    "created_at": "2024-02-07T10:56:32.378Z"
  },
  "expiry": "2025-04-30T00:00:00.000Z",
  "redirect_url": "https://www.starkindustries.com/consent/redirect",
  "flow_type": "gb.commercial.blanket",
  "consent_method": "letter-of-authority",
  "consentee_email_verified": false,
  "meter_numbers": [
    "1234567890",
    "0987654321"
  ],
  "token": "e021c2b1-0afc-4386-9e76-c7713859ae0a",
  "created_at": "2024-04-30T13:21:11.341Z",
  "consented_at": "2024-04-30T13:25:11.796Z",
  "hosted_consent_version": "0",
  "updated_at": "2024-04-30T13:25:11.796Z",
  "revoked_at": "2024-04-30T13:26:06.272Z",
  "hosted_consent_link": "https://consent.openvolt.com/6630f047feb1f65bad24870a?t=e021c2b1-0afc-4386-9e76-c7713859ae04",
  "valid": false
}

api_keys.rotated

Triggered when your Openvolt API keys are rotated. This action can only be done through the dashboard. Triggering an Email on this is super useful just in case others need to be made aware of the change in keys

api_keys.rotated notification has the following schema

{
  "id": "65c361949ecb86c35d5ef1c0",
  "name": "Account Name",
  "email": "[email protected]",
  "live_api_key": "AAAAAAA-BBBBBBB-CCCCCCC-DDDDDDD",
  "readonly": false,
  "created_at": "2024-02-07T10:55:16.577Z",
  "logo": "https://starkindustries.com/logo.png",
}

meter.created

Triggered when new meters are created on the platform. Most likely, you will have asynchronous flows that create meters following the successful consent granted by a customer. Adding a webhook to meter_created lets you know when that meter creation process is complete

meter.created notification has the following schema

{
  "id": "6627ce9cfc558ccc10dc6977",
  "account": "65c361949ecb86c35d5ef1c4",
  "meter_number": "123456789",
  "customer": "65c361e09ecb86c35d5ef1c5",
  "enabled": true,
  "update_frequency": "daily",
  "data_source": "dcc",
  "created_at": "2024-04-23T15:07:08.554Z",
  "validity_state": {
    "missing_consent": true,
    "expired_consent": false,
    "is_disabled_by_user": false,
    "has_invalid_meter_number": false
  },
  "valid": false,
  "status": "inactive"
}

customer.created

Triggered when new customers are created on the Openvolt platform.

customer.created notification has the following schema

{
  "id": "6627795d54dc5b0961a08ae5",
  "account": "65c361949ecb86c35d5ef1c6",
  "name": "Customer Name",
  "email": "[email protected]",
  "address": "Fool's Lane, 1",
  "logo_url": "https://www.starkindustries.com/logo.png",
  "created_at": "2024-04-23T09:03:25.539Z"
}