Define a custom workflow action

Custom workflow actions extend HubSpot’s automation capabilities by allowing your app to perform specialized tasks within workflows. When users build workflows in HubSpot, your custom actions will appear in the action selection panel alongside other workflow actions, enabling seamless integration of your app’s functionality into HubSpot’s automation ecosystem.

When to use custom workflow actions

Use custom workflow actions when you need to:

Integrate external services into HubSpot workflows (e.g., sending data to a third-party API, creating records in external systems).
Perform complex calculations or data transformations that aren’t available in standard workflow actions.
Automate app-specific tasks that users would otherwise need to do manually (e.g., generating documents or triggering notifications in your platform).

Custom workflow actions are ideal when your app needs to be part of HubSpot’s automation ecosystem, rather than just responding to events (which is better handled by webhooks).

Project structure

To define a custom workflow action for an app, create a workflow-actions directory within src/app/. Then, add a configuration file to that directory using the naming convention *-hsmeta.json.

project-folder/
└── src/
    └── app/
        └── app-hsmeta.json
        └── workflow-actions/
            └── workflow-action-hsmeta.json

Custom workflow action configuration

Below are the available configuration options for the *-hsmeta.json file.

You can also use the in-app custom action builder to create workflow actions using a visual tool, then export the JSON to use in the workflow action configuration file.

{
  "uid": "simple_notification_action",
  "type": "workflow-action",
  "config": {
    "actionUrl": "https://example.com",
    "isPublished": false,
    "supportedClients": [
      {
        "client": "WORKFLOWS"
      }
    ],
    "inputFields": [
      {
        "typeDefinition": {
          "name": "message",
          "type": "string",
          "fieldType": "textarea"
        },
        "supportedValueTypes": ["STATIC_VALUE"],
        "isRequired": true
      },
      {
        "typeDefinition": {
          "name": "priority",
          "type": "enumeration",
          "fieldType": "select",
          "options": [
            {
              "value": "high",
              "label": "High Priority"
            },
            {
              "value": "normal",
              "label": "Normal Priority"
            },
            {
              "value": "low",
              "label": "Low Priority"
            }
          ]
        },
        "supportedValueTypes": ["STATIC_VALUE"],
        "isRequired": true
      }
    ],
    "labels": {
      "en": {
        "actionName": "My Custom Action (via Projects V2)",
        "actionDescription": "Sends a notification with custom message and priority level",
        "actionCardContent": "Send {{priority}} priority notification",
        "inputFieldLabels": {
          "message": "Notification Message",
          "priority": "Priority Level"
        },
        "inputFieldDescriptions": {
          "message": "Enter the message to be sent in the notification",
          "priority": "Select the priority level for this notification"
        }
      }
    },
    "objectTypes": ["CONTACT"]
  }
}

Fields marked with * are required.

Field	Type	Description
`uid`*	String	An internal unique identifier for the workflow action.
`type`*	String	The type of component, which should be `workflow-action` in this case.
`actionUrl`*	String	The webhook URL of the API to deliver a workflow execution request.
`isPublished`	Boolean	Determines whether the definition is visible in accounts that installed your app. By default, this is set to `false`.
`supportedClients`*	Array of objects	Specifies the clients that the custom workflow action supports. Each object in the array should have a client key with a string value indicating the client type (e.g., `WORKFLOWS`).
`inputFields`	Array	The values for the inputs that the user has filled out.
`typeDefinition.name`	String	The name or key of the input field.
`typeDefinition.type`	String	The value type that the input field should expect.
`typeDefinition.fieldType`	String	The type of field that appears to users creating the workflow.
`typeDefinition.options`	Array	For enumeration types, this field provides a list of options. Each option must have a `value`, based on the input the user provides, and a `label`, which identifies the option in the workflows tool.
`inputFieldDependencies`	Array	A list of rules that define the relationships between two or more inputs, based on their `dependencyType`. Learn more in the example here.
`labels.<locale>`*	String	Locale key that maps to the locale definition. At a minimum, an english label (`en`) and its definition must be defined.
`labels.<locale>.inputFieldDescriptions`	Object	An object that defines the details for the inputs for your action. In the example above, this object includes `message` and `priority` fields.
`labels.<locale>.inputFieldOptionLabels`	Object	An object that’s required if your input field(s) have options. Provides a map of input field option labels, keyed by the option’s value or label.
`labels.<locale>.outputFieldLabels`	Object	An object that maps the definitions from `outputFields` to the corresponding labels that appear in the workflows tool.
`labels.<locale>.actionName`*	String	The action’s name as shown in the Choose an action panel in the workflows editor.
`labels.<locale>.appDisplayName`*	String	The name of the section in the Choose an action panel where all actions for the app appear. If `appDisplayName` is defined for multiple actions, the first one found will be used.
`labels.<locale>.actionCardContent`	String	A summarized description shown in the action’s card.
`labels.<locale>.executionRules`	Object	An object that maps the definitions from your `executionRules` to messages that will appear for execution results in the workflow’s history.
`objectTypes`	Array	The available CRM object types that this action can be used with. If empty, the action will be available for all object types.
`outputFields`	Array	The values that the action will output that can be used by later actions in the workflow. A custom action can have 0, 1, or many outputs.
`executionRules`	Object	A list of definitions you can specify to surface errors from your service to the user creating the workflow.

​When to use custom workflow actions

​Project structure

​Custom workflow action configuration

When to use custom workflow actions

Project structure

Custom workflow action configuration