Skip to main content

Listening for events

Your integration may need to take action when a specific event happens inside Home Assistant. Home Assistant provides event helpers to listen for particular event types and direct access to the event bus. The helpers are highly optimized to minimize the number of callbacks. If there is already a helper for the specific event you need to listen for, it is preferable to use the helper over listening to the event bus directly.

Available event helpers

Event helpers are available in the homeassistant.helpers.event namespace. These functions return a callable that cancels the listener.

Sync versions of the below functions are also available without the async_ prefix.


unsub = async_track_state_change_event(hass, entity_ids, state_automation_listener)

Tracking entity state changes

FunctionUse case
async_track_state_changeTrack specific state changes
async_track_state_change_eventTrack specific state change events indexed by entity_id
async_track_state_added_domainTrack state change events when an entity is added to domains
async_track_state_removed_domainTrack state change events when an entity is removed from domains
async_track_state_change_filteredTrack state changes with a TrackStates filter that can be updated
async_track_same_stateTrack the state of entities for a period and run an action

Tracking template changes

FunctionUse case
async_track_templateAdd a listener that fires when a template evaluates to 'true'
async_track_template_resultAdd a listener that fires when the result of a template changes

Tracking entity registry changes

FunctionUse case
async_track_entity_registry_updated_eventTrack specific entity registry updated events indexed by entity_id

Tracking time changes

FunctionUse case
async_track_point_in_timeAdd a listener that fires once after a specific point in time
async_track_point_in_utc_timeAdd a listener that fires once after a specific point in UTC time
async_call_laterAdd a listener that is called with a delay
async_track_time_intervalAdd a listener that fires repetitively at every timedelta interval
async_track_utc_time_changeAdd a listener that will fire if time matches a pattern
async_track_time_changeAdd a listener that will fire if local time matches a pattern

Tracking the sun

FunctionUse case
async_track_sunriseAdd a listener that will fire a specified offset from sunrise daily
async_track_sunsetAdd a listener that will fire a specified offset from sunset daily

Listening to the event bus directly

There are two functions available to create listeners. Both functions return a callable that cancels the listener.

  • async_listen_once - Listen once for the event and never fire again
  • async_listen - Listen until canceled

It's a rare case that async_listen is used since EVENT_HOMEASSISTANT_START, EVENT_HOMEASSISTANT_STARTED, and EVENT_HOMEASSISTANT_STOP are only ever fired once per run.

Async context

cancel = hass.bus.async_listen_once(EVENT_HOMEASSISTANT_STOP, disconnect_service)
cancel = hass.bus.async_listen(EVENT_STATE_CHANGED, forward_event)

Sync context

cancel = hass.bus.listen_once(EVENT_HOMEASSISTANT_STOP, disconnect_service)
cancel = hass.bus.listen(EVENT_STATE_CHANGED, forward_event)

Common events

The below events are commonly listened to directly.

Event NameDescription
EVENT_HOMEASSISTANT_STARTCompleted the setup and entered the start phase
EVENT_HOMEASSISTANT_STARTEDCompleted the start phase, and all integrations have had a chance to load; Mostly used by voice assistants and integrations that export states to external services
EVENT_HOMEASSISTANT_STOPEntered the stop phase

Other events

These events are rarely listened to directly unless the integration is part of the core. Often there is a helper available that consumes these events, and in that case, they should not be listened for directly.

Event NameDescriptionPreferred helper
EVENT_HOMEASSISTANT_FINAL_WRITEThe last opportunity to write data to disk
EVENT_COMPONENT_LOADEDAn integration has completed loadinghomeassistant.helpers.start.async_at_start
EVENT_SERVICE_REGISTEREDA new service has been registered
EVENT_SERVICE_REMOVEDA service has been removed
EVENT_CALL_SERVICEA service has been called
EVENT_STATE_CHANGEDThe state of an entity has changedTracking entity state changes
EVENT_THEMES_UPDATEDThemes have been updated
EVENT_CORE_CONFIG_UPDATECore configuration has been updated
EVENT_ENTITY_REGISTRY_UPDATEDThe entity registry has been updatedTracking entity registry changes