> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
---
id: 7f2fab3a-5830-402e-9623-69d1383fcee5
---
# Define a custom workflow action
> Learn how to define a custom workflow action on the latest version of the developer platform.
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](/apps/developer-platform/add-features/configure-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`.
```shell theme={null}
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](/api-reference/latest/automation/workflow-actions/custom-action-builder) to create workflow actions using a visual tool, then export the JSON to use in the workflow action configuration file.
```json theme={null}
{
"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](/api-reference/latest/automation/workflow-actions/custom-action-guide#example-%233). |
| `labels.`\* | String | Locale key that maps to the locale definition. At a minimum, an english label (`en`) and its definition must be defined. |
| `labels..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..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..outputFieldLabels` | Object | An object that maps the definitions from `outputFields` to the corresponding labels that appear in the workflows tool. |
| `labels..actionName`\* | String | The action's name as shown in the *Choose an action* panel in the workflows editor. |
| `labels..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..actionCardContent` | String | A summarized description shown in the action's card. |
| `labels..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. |