Last updated Oct 14, 2024

Prepare your cloud app for Connect migration

This page explains how to prepare your cloud app for migration by registering webhooks.

Webhooks

The webhook that you register is a callback URL to which the app migration platform sends information about migration events. Registering webhooks allows the platform to notify you when specific events take place on your server app. Ensure the endpoint can accept HTTPS POST requests.

Webhook acknowledgement: Your cloud app must return a success response code (HTTP response code 200 OK) as an event acknowledgement within 5 seconds to webhook requests sent by the app migration platform. The app migration platform will send the webhook message in the form of a POST request repeatedly to your cloud app until it receives an acknowledgement.

Verify JWT headers: We strongly recommend you always verify the JWT headers for all events received on your endpoint.

App migration Webhook in Connect descriptor

Marketplace Partners can register their app migration webhook by adding an entry on their Connect descriptor. This is the preferred way to register webhooks to reduce the number of customer app migrations failing due to cloud apps not registering app migration webhook on their cloud sites.

Add webhook migration URL to Connect descriptor

Add a cloudAppMigration.migrationWebhookPath entry to declare app migration webhook in Connect descriptor.

See an example

1
2
{
  // Existing field for base URL
  "baseUrl": "https://your.sample.app.com"
  ...
  ...
  // Existing field for data residency purposes
  // https://developer.atlassian.com/cloud/confluence/data-residency/#enable-data-residency
  "regionBaseUrls": {
    "US": "https://us.your.sample.app.com",
    "EU": "https://eu.your.sample.app.com",
    "AU": "https://au.your.sample.app.com",
    "DE": "https://de.your.sample.app.com"
  }
  ...
  // Field for registering app migration webhooks
  "cloudAppMigration": {
    "migrationWebhookPath" : "/<relative-url-to-baseUrl>"
  }
  ...
}

App migration platform will form the webhook URL to notify app migration events as follows:

For apps NOT supporting data residency, webhook URL will be formed as baseUrl + cloudAppMigration.migrationWebhookPath
For apps supporting data residency, webhook URL will be formed as corresponding regionBaseUrl + cloudAppMigration.migrationWebhookPath

Existing registered webhooks

The current registered webhooks will only be used as an alternative if cloudAppMigration.migrationWebhookPath is not found in the Connect descriptor.

We highly recommend keeping the existing webhook registration in place for sometime as it might take time for customers to update from the older Connect app version.

Precedence of webhooks

The app migration platform will use the following precedence to decide which type of webhook should be used to notify app migration events:

If your cloud app has app migration webhook defined on the Connect descriptor, the app migration platform will use the app migration webhook URL formed from the fields of Connect descriptor as the first choice.
However, if the first choice is not found, the app migration platform will look for and use the app migration webhook which your cloud app registered using the Notification API.
In case the registered webhook is not found, the app migration platform will look for and use a default app migration webhook for your app.

Default app migration webhook in the above precedence is not applicable for all the marketplace partners.

When a webhook is selected according to the precedence above and an attempt to send the event to that webhook fails, there will be retries to deliver the event with same webhook, but there will be no fallback to a different webhook. For example, if a delivery of app migration event to webhook defined in Connect descriptor failed, there will be no attempts to deliver to webhooks registered via Notification API or default app migration webhook. This is intended to be this way because we want our Marketplace Partners to switch over to "App migration webhook in Connect descriptor" as the preferred way to register webhooks.

Alternatively, you can register webhooks as follows:

Register Webhook API

Use the Notification API to register webhooks with the app migration platform.

A sample webhook URL registered via Notification API looks like this: https://example.com/my-migration-listener.

About the Notification API

The endpoints of the Notification API allow you to do the following:

Register webhooks
Get registered webhooks
Delete registered webhooks

The sections that follow explain all the above endpoints, and provide examples on how to use them.

Register webhooks

Use the migration/webhook endpoint to register your webhooks after your app has received the enabled lifecycle event.

We recommend that you register your cloud app to receive lifecycle events to ensure that registering your webhook with the app migration platform is successful.

The app migration platform notifies the webhook URLs specified in request payload (i.e. endpoints field) of the following API when the migrations are ready or available on the server app.

Method	Endpoint	Payload
`PUT`	`migration/webhook`	`{"endpoints" : ["https://<your-url>/<your-notification-api>"]}`

The above endpoint field must contain a non-empty JSON array with an absolute URL/s.

See an example

This section shows you an example of a request and response to register a webhook.

Sample request

1
2
curl -X PUT "https://your-cloud-site/rest/atlassian-connect/1/migration/webhook" \
--header 'Content-Type: application/json' \
--data-raw '{"endpoints" : ["https://<your-url>/<your-notification-api>","https://<your-url>/<your-notification-api2>"]}'

Sample response
```
1
2
200 OK
```

Get registered webhooks

Use the endpoint below to get webhooks that your cloud app has registered with the app migration platform.

Method	Endpoint
`GET`	`migration/webhook`

See an example

This section shows you an example of a request and response get registered webhooks.

Sample request

1
2
curl -X GET "https://your-cloud-site/rest/atlassian-connect/1/migration/webhook" \
--header 'Content-Type: application/json'

Sample response

1
2
{
    "endpoints": [
        "https://<your-url>/<your-notification-api>",
        "https://<your-url>/<your-notification-api2>"
    ]
}

Delete registered webhooks

Use the endpoint below with an empty array to delete or replace existing webhooks for a specific cloud ID.

Method	Endpoint
`PUT`	`migration/webhook`

See an example

This section shows you an example of a request and response to delete existing webhook URLs for a specific cloud ID. For example, if you want to delete all existing webhooks, you can use PUT /migration/webhook with an empty list.

Sample request

1
2
curl -X PUT "https://your-cloud-site/rest/atlassian-connect/1/migration/webhook" \
--header 'Content-Type: application/json' \
--data-raw '{"endpoints":[]}'

Sample response
```
1
2
200 OK
```

Events

The app migration platform provides notifications to your cloud app using the following event types:

Event type	Description
`listener-triggered`	Notifies your cloud app when core product data migration is complete or incomplete. The app migration platform will not notify your cloud app if core product data migration fails.
`app-data-uploaded`	Notifies your cloud app that app data upload to the Atlassian secure cloud storage is complete.
`listener-errored`	Notifies your cloud app that the execution of your server side listener method (`onStartAppMigration`) has stopped with an exception. Please refer to server side exceptions page for more information about this event and follow-up actions for your cloud app. Note: This feature is available for app migrations using CCMA v3.3.7 and JCMA v1.7.2 onwards.
`transfer-cancellation-requested`	Notifies your cloud app that a customer requested a transfer to be cancelled. Please refer to transfer cancellation page for more information about this event and follow-up actions for your cloud app.
`transfer-settled`	Notifies your cloud app when a transfer is settled. Please refer to settling the transfer page for more information about this event and follow-up actions for your cloud app.

The app migration platform may notify your cloud app about events in a different order to the list above. app-data-uploaded may appear before listener-triggered event notifications.

The app migration platform can introduce new event types in addition to above listed event types. New event types can have different event attributes.

It's a good practice to validate the event's payload and return an error response (HTTP 4xx) if the validation fails. This will help you monitor the failed webhook events and investigate for any missing events. We will retry sending the webhook event for this scenario.

Definitions of event attributes

This section provides information you can use to interpret events.

Event attribute	Definition	Examples of application
`eventType`	Specifies the event type.	Your cloud app can respond with a request, based on the event type it receives. For example, it can make a query for mappings.
`cloudAppKey`	The app key installed app key in the cloud site.	NA
`transferId`	An ID (UUID) that the app migration platform uniquely generates per migration for each listener.	Your cloud app must include this UUID when making a request for migration-related mappings.
`messageId`	An ID (UUID) that the app migration platform generates to uniquely recognise an event.	The app migration platform may send duplicate notifications for the same event. Use this ID to detect duplication, if your app is sensitive to duplicate notifications.
`serverAppVersion`	Version of the P2 plugin exporting app migration data (your app).	NA
`migrationId`	An ID (UUID) that the app migration platform uses to uniquely identify a migration.	NA
`migrationScopeId`	An ID that the app migration platform generates to uniquely determine a source (server) and destination (cloud-site) of migration.	NA
`name`	The name of the migration plan provided by the user who initiated the migration.	Use this as a quick way to identify a migration while troubleshooting.
`createdAt`	Timestamp of when the app migration was created.	NA
`jiraClientKey`	This is the `clientKey` of the Jira cloud instance, present in the `installed` lifecycle callback sent to your cloud application during installation.	This value is 'unknown' when the Jira product is not involved in the migration.
`confluenceClientKey`	This is the `clientKey` of the Confluence cloud instance, present in the `installed` lifecycle callback sent to your cloud application during installation.	This value is 'unknown' when the Confluence product is not involved in the migration.
`cloudUrl`	URL of the destination cloud site for the migration.	Use this URL to upload/modify data related to your app migration.
`s3Key`	An ID (UUID) to uniquely identify the data your server app uploads to cloud storage. This will only be present on `app-data-uploaded` events.	Your cloud app must use this ID to request access to ID-specific data in cloud storage.
`label`	Metadata that provides additional information about the data your server app uploads to cloud storage. This will only be present on `app-data-uploaded` events.	NA
`originalTransferId`	When re-running a migration, this attribute represents the transfer ID of the original, unsuccessful migration. Events generated during an original migration don't include this attribute.	Utilize this to distinguish between an original transfer and a rerun transfer. Additionally, it can be used to associate a rerun transfer with its corresponding original transfer.

JSON representation of event object

Confluence migration event object

1
2
{
    "eventType": "listener-triggered",
    "cloudAppKey": "my-cloud-app-key",
    "transferId": "e4166374-2345-4c31-918c-83b14eb644f6",
    "serverAppVersion": "1.0",
    "migrationDetails": {
        "migrationId": "8e60dc59-78d6-484f-966a-a09ff8be8ed0",
        "migrationScopeId": "442bdd69-622d-323d-889d-383b41d8e536",
        "name": "Migration of my Confluence page",
        "createdAt": 1597211035,
        "jiraClientKey": "unknown",
        "confluenceClientKey": "03a7cb4b-23b6-3a79-8916-8824a053e786",
        "cloudUrl": "https://cloud-site-under-migration.atlassian.net"
    }
}

Jira migration event object

1
2
{
    "eventType": "app-data-uploaded",
    "cloudAppKey": "my-cloud-app-key",
    "transferId": "16a84eaa-3f88-4758-94d4-ea245a3b202f",
    "serverAppVersion": "1.0",
    "migrationDetails": {
        "migrationId": "a0b8ed5a-a335-4e0d-b20f-17d821b40c2d",
        "migrationScopeId": "47d54f22-0b9d-4cda-a527-c65ef65f2564",
        "name": "Migration of my jira project",
        "createdAt": 1597193662,
        "jiraClientKey": "acb711b8-a878-356e-abbf-1ae1730308a2",
        "confluenceClientKey": "unknown",
        "cloudUrl": "https://cloud-site-under-migration.atlassian.net"
    },
    "s3Key": "636abf0f-38a2-45c1-8c68-9c7edde97f3f",
    "label": "some-optional-label"
}