Integration tools, accessed in Workshop (Welkin's codeless configuration tool), which allows you to configure Apps and other integrations. You can configure which systems have access to data within Welkin and how they access it.
Integration Tools allows developers and program directors to manage their integrations with Welkin without contacting Developer Support. This is a self serve tool for managing how data flows out of Welkin via Welkin's APIs.
Integration Tools supports:
- Credentials for setting up access credentials.
- Webhooks for getting notifications about changes to data in Welkin.
- Environments for selecting which Welkin instance/environment you want to configure integrations for.
Credentials issued via Integration Tools grants Apps and Integrations access to all the data in the Welkin environment. These
client_secret pair generated by Integration Tools is for syncing data for your entire Welkin environment and is not scoped to specific patients or workers within your Environment.
Each App or Integration you configure for your Welkin Environment should have its own set of credentials for accessing data. Granting separate credentials for each system which has access to Welkin data ensures that if you want to disable a single system you can do this without effecting others.
Credentials created in Integration Tools are active as soon as they are created and can be used to generate access tokens. Access tokens are short lived and are used to make calls to the API. Details on this token exchange process is documented here.
Webhooks specified via Integration Tools send notifications to Apps and Integrations when data is updated in Welkin.
In Integration Tools you select the destination for these webhooks, the method used to secure the data transfer of webhooks, and the credentials used in the selected security method.
When Welkin adds new API endpoints we will not automatically opt in notifications to be sent for those new data types. You must explicitly opt in for each type of notification you want to receive.
You can pause webhooks from this page which prevents us from sending webhooks to your system.
Environments vs Configurations
Environments in Welkin are the entities that house and separate patient data. Each Environment has a separate set of patients and workers. For example, your Test and Live Environments use versions of the same Configuration but house different sets of workers and patients. Some Welkin customers also have a Sandbox which has one configuration called Sandbox and two environments called Sandbox Test and Sandbox Live.
Configurations in Welkin are the collection of settings which define how Welkin will work.
Configurations are published to Environments and control how that Environment will operate.
Integrations and Apps are attached to specific Environments. Credentials give these Apps access to only the data housed within that Environment.
The data housed within an Environment is controlled by the schema defined in the Configuration which is applied to that Environment.
Integration Tools edits Environments and not Configurations.
One webhook per environment
Currently you can only configure one webhook per environment. This limits how many services can receive data from Welkin via webhook.
Webhooks must use valid credential
You can only select valid credentials for securing Webhooks. If you try to invalidate credentials you must first remove them from use with Webhooks.
In the event that you believe one of your access Credentials has been compromised the following procedure should be followed to rotate your Credentials.
A credential could be compromised in the following ways including but not limited to:
- a outside entity gaining access to your credential storage system
- a credential is shared via an insecure channel
- an employee past or present had access to a credential that they should not have
To rotate credentials follow these steps:
- On the Credentials page generate a new Credential (client secret) for the affected Client.
- Begin using this new Credential for sending requests to Welkin
- Add this new Credential to the set of possible keys that are valid for verifying the signature on our Webhook notifications
- On the Credentials page invalidate your old credentials thus ceasing access to Welkin data for the old Credential
- On the Webhooks page update the keys used for signing our Webhook notifications
- Remove the old credentials from validating the signature of the Webhooks
- Rotation process is complete