Custom Integrations are used by Workplace customers for in-house development (or bespoke development for the sole use of a single Workplace customer) to integrate their own tools or software ecosystem with Workplace.
In this section, we will learn how to create and configure a Custom Integration on Workplace.Creating an integration
Creating an integration
To create an integration, log in as an Administrator who has the permission to change company settings and configure integrations. Once you're logged in you can complete the following steps to create an integration:
Once you have created the integration, you can proceed to configure it.
In the Integrations section of the Admin Panel, click the name of the integration to be configured. These are the fields you may find in the Integration details screen.
- Integration details: You can modify the Name, logo and description of the integration, see the App ID and App Secret, and create or reset the Access token of your integration.
The Access token is required to send any API request so Workplace can verify and validate that the integration is sending those requests. Saving the Access token in a secure place is highly recommended since it can be used to perform critical actions on Workplace, such as creating or deactivating user accounts (provided that the integration has the corresponding permissions).
- Visibility: You can enable or disable your integration. If it's disabled, the integration will not be able to make any API request.
You can also enable or disable its discoverability, which will make your integration appear in the list of available bots on Workplace.
- Last API request: You can view the last day that the integration made an API request and the number of requests made in the last seven days.
- Delete integration: You can delete the integration. This action is not reversible and will delete the integration and its associated content.
In the configuration screen of the integration, there is a section called Pemissions in which you can choose the permissions that your integration will need access to. Below you have the list of permissions.
To learn more about the Custom Integration permissions, please visit the Developers Documentation.
Another section available to configure for each integration is Webhooks. Webhooks allow you to subscribe to specific events and receive updates in real time. When a change occurs in Workplace, an HTTPS POST request is sent to a callback URL for each custom integration app that's subscribed to the relevant webhook topic.
One example of a webhook can be receiving an update in the callback URL when a comment has been created in a post.
Webhooks are divided into topics, and you can set a different callback URL per topic. More info on the topics and subscriptions available can be found in the Developers Documentation.
Subscribing to a webhook
More info on how to subscribe and action a webhook can be found in the Developers Documentation.
You can set two types configurations here:
- Server IP allow list, where you can allow list IP addresses to only admit API calls that come from those IP addresses.
- Require app secret proof, where you can enable an additional layer of security that will require you to pass the app secret details when making an API call.
The last section of the configuration is Link preview, which is only used by integrations that want to implement previews for links/urls on Workplace. All details can be found in the Developers Documentation.Examples
You can find some code samples in our Github repository, and some chat bot examples here.