Create custom workflow actions with the action builder

• Speed up development by previewing how your action will display in HubSpot before writing any code.
• Reduce errors with a guided setup that outputs the correct JSON for workflow action schema files and API requests.
• Streamline testing by ensuring your action looks and behaviors as expected before implementation.

• Create a developer account.
• If you plan to add the custom workflow action to an app built on the developer platform, create an app.

​

Use the builder

• In your app developer account, navigate to Apps.
• Click the app that you’d like to build the workflow action for.
• In the left sidebar menu, click Workflows custom action builder.

• In the top right, click Import action definition.
• In the dialog box, enter your action definition.
• At the bottom, click Import. The editor will automatically be populated based on the action definition.

​

Add inputs

• To begin building your custom workflow action, click Add input. These are the inputs that the action receives and will be filled by the user in-app when setting up the action.
• In the left panel, select an input field type for your action. Then, set up your input:
  • Field type: the field type for your input.
  • Label: the user-facing label for your input.
  • Key: the key the input’s data is returned under. This value must match your external API. For example, if your external API expects a user’s email address to provided using the parameter name user_email, but the key you specify in the workflow action builder is email_address, the API wouldn’t be able to match the data sent.
  • Tooltip: add an information icon next to the label which displays the configured text within a tooltip.
  • Options: set up values for your input field. This field will appear if you’ve selected the Radio select, Dropdown select, or Multi-select field type options. You can manually set up static options, or use external data to populate your options.
  • Required field: determine if the input as required or not. After setting up your input, in the bottom, click Save. A preview of the input will appear in the right panel.

• To add another input, in the left sidebar menu, click the + plus icon.
• To add any dependencies to the input field, at the top, click the Dependencies tab.
• Click Add field dependencies. For example, you can choose to hide or grey out a field, based on the value of this field.
• Set up your field dependencies:
  • Choose which inputs should be dependent on this: select the other input fields that you want to dependent on the field.
  • Choose what behavior you want to control: choose if this field controls the visibility or state of the field. For example, you can choose whether the field is hidden or greyed out.
  • Only show if the current fields value is equal to: set the value to control the dependency.
• To add another dependency, click + Add input field dependency.
• To remove a dependency, click the delete icon next to the dependency group.

​

Add action details

• In the left sidebar menu, click the + plus icon.
• In the Basic info tab, set up your action details:
  • Display name: enter a name for your workflow action. This’ll appear when selecting and setting up the workflow action.
  • Available object types: select the CRM object types that this action can be used with. If an option isn’t selected, the action will appear in all workflow types.

• At the top, click the Action card tab. You can configure how the action card appears when selecting a workflow action from the editor.
• Enter a description for the workflow action card. You can review your action card in the section below.

​

Set up the API request triggered by your action

• In the left sidebar menu, click the API icon.
• In the Request panel tab, enter a Request URL for your workflow action.
  • This will be the URL where an HTTPS request is sent when the action is executed.
  • The request body will contain information about which user the action is executing on behalf of, and what values were entered for the input fields.
• To set up your API outputs, click the Outputs tab. These are values that the action will output that can be used by later actions in the workflow. A custom action can have zero, one, or many outputs.
• Click Add output. Then, set up your output:
  • Response key: the name of the parameter that your external API returns that can be used as an input in subsequent actions. For example, if the output from your external API includes a property named computed_output, you’d provide that property name for the Response key here.
  • Label: the user facing output label.
  • Data type: the field data type for your output.
• After setting up your output, at the bottom, click Save.

​

Manage inputs

• In the left sidebar menu, click the Inputs icon.
• To add additional information to your workflow action, click to toggle the Add additional info above inputs switch on.
• In the Additional info field, enter any additional information for your workflow action. For example, you can enter a brief description of what the action does, or any additional requirements or behavior that users should note when using the action.

​

Set up action logs

• In the left sidebar menu, click the Action logs icon.
• Click Add action log.
• Set up your action log:
  • Key: the unique identifier for this action log message.
  • Message: the message to show to users if the conditions for this action log are met.
  • Conditions: the action’s execution response determines which action log message to show. Choose what values should be present in the response object to show this log message.
• Enter a Key and Value for your condition.
• To delete a condition, click the delete icon.
• To add another condition for your action log, click + Add another condition.
• After setting up your action log, at the bottom, click Save.

​

Use your custom workflow action