Guides

Lifecycle events

Suggest Edits

A plug-in can register to be notified about certain lifecycle events via a web-hook callback. Thus the plug-in can get notified when it is installed for a Haiilo Home tenant, when it is uninstalled from a Haiilo Home tenant, when a plug-in instance (i.e. a plug-in widget) is added or removed.

Haiilo Home then asynchronously sends a POST request containing all relevant information to the registered callback URL. If unanswered, requests time out after 30 seconds and will be retried several times. The plug-in install event is an exception and needs to be received by your plug-in back end.

Registering a lifecycle callback

To register for a lifecycle event, add the lifecycle attribute to your plug-in’s manifest. Its value is a list of the events your plug-in is interested to be notified about and a URL at which the callbacks for each event are implemented:

"lifecycle": {
    "url": "/lifecycle/",
    "events": [
      "install",
      "uninstall"
    ]
  }

Implementing the lifecycle API

Haiilo Home sends POST requests to the given lifecycle callback URL. In order to receive those messages the plug-in must implement Haiilo Home’s plug-in lifecycle events web-hook API. Following the manifest example from above the install web-hook will have to be implemented at https://your-plugin.com/lifecycle/install.

Each request contains a single entry token in its body. The content is a signed JWT token where the payload holds the event data. The payload differs for each event. See the detailed description in the OpenAPI documentation below.

Lifecycle events

install

The install event is special because it is not sent asynchronously and forgotten about, but Haiilo Home waits for a successful response (status 201) from the plug-in backend. This behaviour can be used by plug-in developers to prevent their plug-in from being installed to a Haiilo Home tenant they do not accept. It is respectively important that if registered as a web-hook in the manifest, the plug-in backend has to be available and respond to the install call appropriately. Otherwise the plug-in will not be able to be installed.

See: Life cycle event 'install'

uninstall

The uninstall event is sent when a Haiilo Home admin uninstalls the plug-in from a Haiilo Home tenant. The plug-in is uninstalled no matter what the response to this call is. The uninstall event also implicates that all plug-in instances (widgets) are removed. In this case there will be no explicit instance_remove event for any existing plug-in instances.

See: Life cycle event 'uninstall'

instance_add

The instance_add event is sent when a plug-in instance is added, more specifically when a layout containing a new plug-in instance (widget) is saved. Thus the instance_add event is sent after the plug-in is initially rendered in the edit view of a layout. The plug-in instance is added no matter what the response to this call is.

See: Life cycle event 'instance_add'

📘

The even's srcId claim corresponds to the src query parameter upon plug-in initialization and is a unique identifier for the plug-in instance.

instance_remove

The instance_remove event is sent when a plug-in instance (widget) is removed from a layout and the layout is saved. If the plug-in instance is removed due to the uninstall of the whole plug-in, no explicit instance_remove event for any existing plug-in instances will be sent.

See: Life cycle event 'instance_remove'

📘

The even's srcId claim corresponds to the src query parameter upon plug-in initialization and is a unique identifier for the plug-in instance.

References

Lifecycle 1.1.0 Open API 3.0

Updated about 1 year ago