Migrating From Custom Integrations to Third Party Apps

Introduction

This page summarizes the key activities for ISVs that need to migrate a Workplace integration from Custom Integrations to Third Party Apps, which is mandatory for all SaaS and PaaS products.

If you don't have a third party app yet, you must submit an app creation request. Submit a distinct request for each product that you would like to offer to Workplace customers.

Technical Considerations

While most of the functional API calls (e.g., messaging, iterating feeds) are shared between Custom Integrations and Third Party Apps, there are some key technical differences between the two app types, which are summarized here.

  • Installation Flow

Custom Integrations rely on a System Admin manually generating an access token within the Workplace UI and then providing that value to the API client through some configuration scheme.

In contrast, Third Party Apps eliminate the need for this manual step. Instead, you need to build software to implement one or more Third Party App install flows so that your software can retrieve an access token using a server-to-server API call when an admin chooses to install your product.

  • Access Tokens

Custom Integrations have a single App ID and a single access token. The access token can be used by itself to authenticate API calls.

In contrast, Third Party Apps have a single App ID but many access tokens -- one per installation. This implies that you will need a mechanism to read/write the access token for a particular install when appropriate. Note that you can fetch metadata about an install after you've retrieved the access token.

Third party apps also require an app-secret proof to be supplied along with the access token itself to authenticate API calls.

  • Webhooks

Custom Integrations may establish webhook subscriptions, if necessary. Each webhook subscription is associated with the Custom Integration and has its own callback_url. In effect, this means that each "installation" of a Custom Integration can have its own set of callback URLs.

In contrast, Third Party Apps have one set of webhook subscriptions for all installations of that app. To distinguish webhook POST requests from one customer to another, Workplace includes the community_id (and if relevant, the page_id) within the webhook request body.

  • User IDs

Custom Integrations see native user IDs via the APIs and webhooks (e.g., the same ID as is included in a user's profile URL in Workplace (e.g., https://work.workplace.com/profile.php?id=100010000000000).

In contrast, Third Party Apps see App-Scoped IDs via the APIs and webhooks, which means that you may need to do a data conversion upon changing from a Custom Integration to Third Party app install.

  • App Uninstalls

Third Party apps are required to subscribe to the uninstall webhook event, which notifies you if an admin decides to remove your app from Workplace.

When you receive this event, you must delete all Workplace customer data and configuration related to this community from your system unless you are required to keep this data by law or because of a separate agreement with the customer.