Building Your Own Integration with a Custom Node

Overview

You can build your own integration for any service with an API by combining an HTTP REST Request node, a stored API key, and a custom node. In this article, we'll be covering how to build a workflow that calls an API, store the API key as a secret, and turn the result into a node your whole team can reuse.

We'll use a vendor lookup as the example. Replace the URL, inputs, and output with the details of your own API.

To learn what a custom node is, see Understanding custom nodes.

Understand why this approach works

Every custom node runs a workflow underneath. That workflow holds the API call and references the API key. The workflows that use the node only see its inputs and output.

• The API key is stored once, as a secret, instead of being pasted into every workflow.
• Anyone building a workflow can use the integration without knowing the API.
• If the API changes, you update one workflow. If the key changes, you update one secret.

Store the API key as a secret

1. Go to Workflows > Settings > Secrets.
2. Add a secret with the key VENDOR_API_KEY and paste your API key as the value.
3. Save.

Storing a secret requires permission to edit workflow secrets. An administrator can grant this permission to any role in Admin Settings.

Define the inputs your team will fill in

The trigger's inputs become the node's inputs. Add only what someone using the node needs to provide.

1. Create a new workflow named for your integration, such as Vendor lookup.
2. Open the workflow's Trigger node and set the trigger type to Manual.
3. Add an input named accountId and mark it required.

For input schema options, see Configuring the workflow trigger input schema.

Add the HTTP REST Request node

1. In the Graph View, click the + icon after the trigger.
2. Open the HTTP tab and select HTTP REST Request.
3. Set Method to the HTTP method your API expects, such as GET.
4. Set URL using a function input that reads the trigger input:

({ state }) => `https://api.vendor.example/accounts/${state.input.accountId}`

5. Set Headers using a function input that reads the secret:

({ secrets }) => ({ Authorization: `Bearer ${secrets.VENDOR_API_KEY}` })

Match the header format your API expects. Some APIs use a custom header, such as X-API-Key, instead of a bearer token. Use Params for query parameters and Body for request payloads.

For every field on the node, see HTTP request nodes.

Return only the data you need

An API response is often large. Use the output mapper on the workflow's End node to return just what the next workflow needs. Whatever you return here becomes the node's output.

1. Select the End node.
2. In its output mapper, return the fields you need, such as vendorName and status.

For details, see Using output mappers.

Optionally, describe the fields you return so people using the node get accurate suggestions in later steps:

1. On the End node, set Type of output to JSON.
2. Click Add output schema and describe fields such as vendorName and status.

For more, see Understanding custom nodes.

Test and publish the workflow

1. Run a test with a real accountId and confirm the output.
2. Publish the workflow.

A workflow needs a published version before it can become a node.

Convert the workflow to a node

1. Click the … menu next to the workflow name.
2. Select Convert to node.
3. Confirm in the Convert this workflow to a node? dialog.

The node now appears in the node library under the workflow's name.

Use your integration in another workflow

1. Open any workflow and click the + icon where you want to add the node.
2. Open your organization's section, then the Custom nodes folder.
3. Select Vendor lookup.
4. Set accountId in the side panel, using a value from an earlier node if you need to.

The node's output is available to later nodes, like the output of any other node.

Editing the backing workflow changes the node for every workflow that uses it. To rotate the API key, update the secret under Workflows > Settings > Secrets.