Documentation

Lifecycle

Allows an add-on to register callbacks for events that occur in the lifecycle of an installation. When a lifecycle event is fired, a POST request will be made to the appropriate URL registered for the event.

The installed lifecycle callback is an integral part of the installation process of an add-on, whereas the remaining lifecycle events are essentially webhooks.

Each property in this object is a URL relative to the add-on's base URL.

Lifecycle attribute example

{
  "installed": "/installed",
  "uninstalled": "/uninstalled",
  "enabled": "/enabled",
  "disabled": "/disabled"
}

Lifecycle HTTP request payload

Lifecycle callbacks contain a JSON data payload with important tenant information that you will need to store in your add-on in order to sign and verify future requests. The payload contains the following attributes:

{
  "key": "installed-addon-key",
  "clientKey": "unique-client-identifier",
  "sharedSecret": "a-secret-key-not-to-be-lost",
  "serverVersion": "server-version",
  "pluginsVersion": "version-of-connect",
  "baseUrl": "http://example.atlassian.net",
  "productType": "jira",
  "description": "Atlassian JIRA at https://example.atlassian.net",
  "serviceEntitlementNumber": "SEN-number",
  "eventType": "installed"
}
Attribute Description
key Add-on key that was installed into the Atlassian Product, as it appears in your add-on's descriptor.
clientKey Identifying key for the Atlassian product instance that the add-on was installed into. This will never change for a given instance, and is unique across all Atlassian product tenants. This value should be used to key tenant details in your add-on. The one time the clientKey can change is when a backup taken from a different instance is restored onto the instance. Determining the contract between the instance and add-on in this situation is tracked by AC-1528 in the Connect backlog.
publicKey Deprecated This is the public key for this Atlassian product instance. This field is deprecated and should not be used.
sharedSecret Use this string to sign outgoing JWT tokens and validate incoming JWT tokens. Optional: and may not be present on non-JWT add-on installations, and is only sent on the installed event.
serverVersion This is a string representation of the host product's version. Generally you should not need it.
pluginsVersion This is a semver compliant version of Atlassian Connect which is running on the host server, for example: 1.1.15.
baseUrl URL prefix for this Atlassian product instance. All of its REST endpoints begin with this `baseUrl`.
productType Identifies the category of Atlassian product, e.g. jira or confluence.
description The host product description - this is customisable by an instance administrator.
serviceEntitlementNumber (optional) Also known as the SEN, the service entitlement number is the add-on license id. This attribute will only be included during installation of a paid add-on.
oauthClientId The OAuth 2.0 client ID for your add-on. For more information, see OAuth 2.0 - JWT Bearer token authorization grant type

Request query parameters

When this payload information is POSTed to your Atlassian Connect service you may receive the user_key and user_id query parameters; these query parameters are both deprecated. Deprecated If you wish to find out which user enabled your add-on then you should extract the context.user.userKey or context.user.userName data from the JWT token on the enabled lifecycle event.

Properties

disabled

Type
string

uri
Description

Fires when an add on has been successfully disabled. This is an asynchronous notification event.

enabled

Type
string

uri
Description

Fires when an add on has been successfully enabled. This is an asynchronous notification event.

installed

Type
string

uri
Description

When a Connect add-on is installed, a synchronous request is fired to this URL to initiate the installation handshake. In order to successfully complete installation, the add-on must respond with either a 200 OK or 204 No Content status.

Important

Upon successful registration, the add-on must return either a 200 OK or 204 No Content response code, otherwise the operation will fail and the installation will be marked as incomplete.

uninstalled

Type
string

uri
Description

Fires when an add on has been successfully un-installed. This is an asynchronous notification event.