Extension Creation

Integration Toolkit > Extension Creation

Partners can build custom integrations that connect external systems with Oneflow and publish them to the Oneflow Marketplace. Refer to the image below for examples of existing integrations within Oneflow.

📘

Note:

If you would like to create an integration with Oneflow, please email [email protected] along with details of your app.

To create an integration with Oneflow, you should have a proper Authentication structure along with the following additional details required by Oneflow.

• Authentication method
• Setup URL if you selected "Automatic" authentication method.

Therefore, to create the extension, you may provide a Setup URL beforehand. Additionally, your system may expose two endpoints: one for initial setup(Setup URL) and one to receive webhook events from Oneflow(Webhook URL).

After the extension is created, the extension card will appear in the Marketplace in Oneflow under the relevant category.

Example: If your integration name is Demo

Further steps to ensure your extension is usable

You can create a Template Group and Webhook related to your integration for a user's Oneflow account while that user is authenticating and setting up your integration, as explained here. You’ll find a summary of some related entities below.

Such that, you will have to:

• Create a Template group to distinguish contracts created using your integration from other integrations
• Create a Webhook if you want to receive Oneflow notifications
• Add a Sign key to your Webhook (optional)
• Add Data fields to your Template Group, if you want to transfer individual variables from your system to the Oneflow contract.

Setup URL

The Setup URL is an endpoint provided by you (external system) where Oneflow redirects users after they enable the extension. This URL typically handles additional configuration steps, such as validating the integration, generating access tokens, or displaying a success page to confirm that the setup is complete.

Example: https://your-external-system.com/api/integrations/oneflow/setup

Webhook

A Webhook URL is an endpoint in your system designed to receive real-time notifications from Oneflow. For example, when specific events occur in Oneflow, such as a contract being signed or published, Oneflow sends a request to your webhook URL containing the event details. This allows you to respond automatically, such as updating records in your system or triggering relevant workflows.

Example: https://your-external-system.com/api/webhooks/oneflow/events

Sign key

A Sign key is a cryptographic key used to verify the authenticity of webhook notifications sent by Oneflow. When Oneflow dispatches a webhook request, it includes a signature generated using this key. You can use the sign key in your external system to validate the signature, ensuring the request originates from Oneflow and maintaining secure and trusted communication.

Example: sign key: b84e5d34-8f3b-4728-a8f7-12345abcde67

Template group

The Template group is important to associate the contracts you have created with your integration. This is to distinguish the contracts created using your integration from other integrations. Additionally, you can get webhook notifications from the contracts created using your template group separately if you have a webhook linked to your template group. You can also add data fields to this template group, which can be used with your integration when creating contracts.

Example: Demo Template

Data fields

Data fields are important if you want to transfer any individual variables from your system to the Oneflow contract. Therefore, to use data fields, you have to create a template group for your integration, as mentioned above. You can then update your template group with the data fields you want to add to Oneflow contracts. The contract with data fields should use a template associated with your integration’s template group.

Example: Let’s say your system is an HRM system, and you are going to create contracts with employees. Then you can create and add data fields as variables to the template group (Ex: Demo Template) like the following.

📘

Note:

To get an idea of creating and using template group with data fields and webhooks for notifications, refer the corresponding sections in Configure Template group and Webhook section.