Events - Flatpeak

Flatpeak records an event when something changes. Receive events as webhooks, or list them with list all events, filtered by type or object_id. Every event has the same envelope. data carries IDs only, so retrieve the object before you act. Ignore types you do not handle, because more can be added.

Event

{
  "id": "evt_66ba59f1d3a47e2c9f81b0a2",
  "object": "event",
  "live_mode": true,
  "type": "tariff.expired",
  "data": {
    "device_id": "dev_9c1f70a4e2b6485db3f0c8a1",
    "tariff_id": "trf_66ba584eb6923d7c3b942ef6"
  },
  "time_created": "2026-02-01T11:25:39Z"
}

Tariff

Event	Fires when	Do
`connect_session.complete`	A Connect session completes for the device	Retrieve the session. When `price_available` is `true`, read prices. After a VPP session, list the device’s enrollments
`price.update`	Prices or the solar forecast at the location change	Re-fetch prices and re-run optimizations
`tariff.expiring`	The tariff nears its end date	Ask the user to renew or reconnect
`tariff.expired`	The tariff reached its end date or became invalid	Ask the user to reconnect in Connect
`tariff.fetch.failed`	Flatpeak cannot read the tariff from the supplier after repeated attempts, for example because credentials expired	Ask the user to reconnect in Connect
`tariff.connection.upgrade`	A better connection exists for the supplier, usually a direct integration	Ask the user to reconnect to take it
`tariff.report.resolved`	Flatpeak fixed a tariff error the user reported in Connect, and the connection is `CONNECTED` again	Optional: tell the user

Supplier consent lasts 1 to 3 years and ends sooner if the user moves or switches supplier. A tariff change with the same supplier needs no action, because Flatpeak updates the tariff.

VPP

Event	Fires when	Do
`vpp_enrollment.update`	The device’s enrollment changes state or step	Retrieve the enrollment. Read `enrollment_state`, `enrollment_step` and `suspension_reasons`
`vpp_event.update`	A VPP event that draws on your devices is created or changes status. It fires once per status change and covers all your devices in the event	Retrieve the event. At `LOCKED`, read each device’s share from `allocation`, apply it and confirm. This is time-sensitive
`device.instructions.update`	A plan changes for a device on a managed tariff	Retrieve the instructions, apply and confirm. This is time-sensitive
`device.update`	The device changes, including its `telemetry` duties and delay flags, its `capabilities`, or its `consents` when the user grants or withdraws consent	Retrieve the device. Adjust the feeds you submit and their intervals, and catch up a feed that `telemetry` marks as delayed. For a consent change, read consent history
`location.update`	The location changes, including its `metering`	Retrieve the location and refresh your cached copy. If `metering.conflict` is `true`, set `capabilities.metering.location` to `false` on the device that does not meter the connection point. Until then, the last write wins
`device.settings.update`	The device’s settings change, from either app or on the device	Retrieve the settings, apply them to the device and confirm in your next state submission
`device.settings.sync_failed`	The device has not applied a settings change in the expected window	Check the device and re-fetch the settings. Your next state submission resolves `sync_status`

Without VPP, device.update and location.update need no action.

Event data

Event	`data`
`connect_session.complete`	`connect_session_id`, `device_id`
`price.update`	`location_id`
`tariff.expiring`	`device_id`, `tariff_id`
`tariff.expired`	`device_id`, `tariff_id`
`tariff.fetch.failed`	`device_id`, `tariff_id`
`tariff.connection.upgrade`	`device_id`, `tariff_id`
`tariff.report.resolved`	`device_id`, `tariff_id`, `report_id`
`vpp_enrollment.update`	`device_id`, `enrollment_id`
`vpp_event.update`	`vpp_event_id`
`device.instructions.update`	`device_id`
`device.update`	`device_id`
`location.update`	`location_id`
`device.settings.update`	`device_id`
`device.settings.sync_failed`	`device_id`