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.

App migration webhooks for Connect and Connect On Forge Apps

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>"
  }
  ...
}

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.

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.

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.

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.

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:

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.

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"
}