Skip to main content
Use HubSpot’s workflows tool to automate business processes and improve team efficiency. You can create custom workflow actions to integrate your service with HubSpot’s workflows. After setting up your custom action, when users install your application, they can add the custom action to their workflows. When those workflows execute, HTTPS requests will be sent to the configured URL with the payload that you set up. Requests made for your custom action will use the v2 version of the X-HubSpot-Signature. Learn more about validating requests from HubSpot. For more information on defining your custom workflow action, refer to the custom workflow action reference. You can also skip forward to the following sections:

​
Before you get started

  • You’ll need to create an app. Your app logo will be used as the icon for the custom action.
  • When your custom workflow action needs to make requests to HubSpot APIs, you must authenticate those calls using OAuth tokens (for Marketplace apps) or static auth tokens (for single-account apps) based on your app’s authentication configuration.

​
Define your custom action

To create a custom workflow action, you’ll need to define the action using the following fields. This also specifies the request format for requests coming from HubSpot, as well as the handling of responses from your service.
  • actionUrl: 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.
  • objectTypes: which CRM objects this action can be used with.
  • published: by default, custom actions are created in an unpublished state. Unpublished actions are only visible in the developer portal associated with your HubSpot application. To make a custom action visible to users, update the published flag on your action definition to true.
  • inputFields: the inputs that the action receives. These will be filled by the user.
  • inputFieldDependencies: these rules define the relationships between two or more inputs, based on their dependencyType. You can use the following dependencyType options:
    • SINGLE_FIELD: these rules allow fields to be grayed out until other fields meet specific conditions. Use this to make sure a field is pre-filled before allowing visitors to continue filling out the rest of the form. Controlling (parent) fields will provide values to the corresponding dependent (child) fields.
    • CONDITIONAL_SINGLE_FIELD: these rules allow fields to be hidden until other fields meet specific conditions. Use this to show or hide specific fields based on a previous selection. For example, if your business is a bakery, you can add a checkbox to ask visitors if they like cake and, only if the checkbox is selected, display a field to ask what flavor of cake they like.
  • outputFields: the values that the action will output. These values can be used by later actions in the workflow. A custom action can have zero, one, or many outputs.
  • objectRequestOptions: properties of the enrolled object included in the payload to the actionUrl.
  • labels: copy that describes to the user what the action’s fields represent and what the action does. English labels are required, but labels can be specified in any of the following supported languages as well:
    • French (fr)
    • German (de)
    • Japanese (ja)
    • Spanish (es)
    • Brazilian Portuguese (pt-br)
    • Dutch (nl)
    • Polish (pl)
    • Swedish (sv)
    • Italian (it)
    • Danish - Denmark (da_dk)
    • Finnish (fi)
    • Norwegian (no)
    • Traditional Chinese - Taiwan (zh-tw)
  • executionRules: a list of definitions you can specify to surface errors from your service to the user creating the workflow.
  • functions: code snippets that are run in order to transform the payload being sent to a url or transform the response from that url.

​
Example custom action definition

{
  "actionUrl": "https://webhook.site/1234a-567b-8910c",
    "requiresObject": true,
    "objectTypes": [
    "CONTACT",
    "COMPANY"
  ],


  "inputFields": [
    {
      "isRequired": true,
      "supportedValueTypes": [
        "STATIC_VALUE"
      ],
      "typeDefinition": {
        "fieldType": "text",
        "name": "staticInput",
        "type": "string"
      }
    },
    {
      "isRequired": false,
      "supportedValueTypes": [
        "OBJECT_PROPERTY"
      ],
         "typeDefinition": {
        "fieldType": "select",
        "name": "objectInput",
        "options": [
          {
            "value": "annual_revenue",
            "displayOrder": 0,
            "label": "Annual Revenue"
          },
          {
            "value": "monthly_revenue",
            "displayOrder": 1,
            "label": "Monthly Revenue"
          }
        ],
        "type": "enumeration"
      }
    },
    {
      "isRequired": false,
      "supportedValueTypes": [
        "STATIC_VALUE"
      ],
      "typeDefinition": {
        "fieldType": "select",
        "name": "externalOptionsInput",
        "options": [],
        "type": "enumeration",
        "optionsUrl": "https://webhook.site/1234a-567b-8910c"
      }
    }
  ],
      "inputFieldDependencies": [],
          "outputFields": [
    {
      "typeDefinition": {
        "externalOptions": false,
        "options": [],
        "label": "myOutput",
        "name": "myOutput",
        "type": "string"
      }
    }
  ],
             "objectRequestOptions": {
    "properties": [
      "email"
    ]
  },

  "labels": {
    "en": {
      "inputFieldLabels": {
        "staticinput": "Static Input",
        "objectInput": "Object Property Input",
        "optionsInput": "External Options Input",
        "externalOptionsInput": "External Options Input"
      },
      "actionName": "My Extension 2025",
      "actionDescription": "My Extension Description",
      "executionRules": {},
      "inputFieldDescriptions": {
        "staticinput": "",
        "externalOptionsInput": ""
      },
      "inputFieldOptionLabels": {
        "staticinput": {},
        "externalOptionsInput": {},
   "objectInput": {
          "annual_revenue": "Annual Revenue",
          "monthly_revenue": "Monthly Revenue"
        }

      },
      "outputFieldLabels": {
        "myOutput": "myOutput"
      }
    }
  },


      "executionRules": null,
  "functions": [ {
      "functionType": "POST_FETCH_OPTIONS",
      "functionSource": "exports.main = (event, callback) => {\r\n  callback({\r\n    \"options\": [{\r\n        \"label\": \"Big Widget\",\r\n        \"description\": \"Big Widget\",\r\n        \"value\": \"10\"\r\n      },\r\n      {\r\n        \"label\": \"Small Widget\",\r\n        \"description\": \"Small Widget\",\r\n        \"value\": \"1\"\r\n      }\r\n    ]\r\n  });\r\n}"
    }]

}
The above definition will render the following in the workflows tool:
example rendering of custom code action
There are two types of calls made for custom workflow actions:
  • Field option fetches: populate a list of valid options when a user is configuring a field.
  • Action execution requests: made when an action is being executed by a workflow that includes your custom action.

​
Test and publish your custom action

After creating your new custom action, you can test then publish it.

​
Testing custom actions before publishing

Before publishing your custom action, you can test action execution and fetching options by pointing the URL to webhook.site. This allows you to inspect the payload and return a specific response. You can also test the action in your developer portal by creating a workflow in the workflows tool. Then, adding your new action. When you complete your testing, it’s recommended to archive your test actions.

​
Publishing custom actions

By default, custom actions are created in an unpublished state. Unpublished custom actions are only visible in the developer portal associated with the corresponding HubSpot application. To make a custom action visible to users, update the published flag on your action definition to true. If an action is unpublished, portals that have already added the action to their workflow will still be able to edit and execute already added actions. But, they won’t be able to add the action to the same or any other workflows again.

​
Custom action examples

The code snippets below provide examples of several common use cases for custom actions, such as defining a widget or invoking a serverless function.

​
Defining a widget

The following example sends data to create a new widget in your external system whenever the workflow is triggered. This example features the following input fields, created for contact and deal workflows:
  • widgetName: a static input field
  • widgetColor: a dropdown field with options
  • widgetOwner: a field representing a HubSpot owner.
  • widgetQuantity: a field that’s derived from a property (that the user creating the workflow selects) on the enrolled object.
{
  "actionUrl": "https://example.com/hubspot",
  "inputFields": [
    {
      "typeDefinition": {
        "name": "widgetName",
        "type": "string",
        "fieldType": "text"
      },
      "supportedValueTypes": ["STATIC_VALUE"],
      "isRequired": true
    },
    {
      "typeDefinition": {
        "name": "widgetColor",
        "type": "enumeration",
        "fieldType": "select",
        "options": [
          { "value": "red", "label": "Red" },
          { "value": "blue", "label": "Blue" },
          { "value": "green", "label": "Green" }
        ]
      },
      "supportedValueTypes": ["STATIC_VALUE"]
    },
    {
      "typeDefinition": {
        "name": "widgetOwner",
        "type": "enumeration",
        "referencedObjectType": "OWNER"
      },
      "supportedValueTypes": ["STATIC_VALUE"]
    },
    {
      "typeDefinition": {
        "name": "widgetQuantity",
        "type": "number"
      },
      "supportedValueTypes": ["OBJECT_PROPERTY"]
    }
  ],
  "labels": {
    "en": {
      "actionName": "Create Widget - Example 1",
      "actionDescription": "This action will create a new widget in our system. So cool!",
      "actionCardContent": "Create widget {{widgetName}}",
      "inputFieldLabels": {
        "widgetName": "Widget Name",
        "widgetColor": "Widget Color",
        "widgetOwner": "Widget Owner",
        "widgetQuantity": "Widget Quantity"
      },
      "inputFieldDescriptions": {
        "widgetName": "Enter the full widget name. I support <a href=\"https://hubspot.com\">links</a> too.",
        "widgetColor": "This is the color that will be used to paint the widget."
      }
    }
  },
  "objectTypes": ["CONTACT", "DEAL"]
}

​
Invoking a serverless function

The following custom action example uses a serverless function to transform the payload that is sent to the configured actionUrl. Since the objectTypes field isn’t specified in the custom action definition, this action will be available in all workflows types. 
{
  "actionUrl": "https://example.com",
  "inputFields": [
    {
      "typeDefinition": {
        "name": "widgetName",
        "type": "string",
        "fieldType": "text"
      },
      "supportedValueTypes": ["STATIC_VALUE"],
      "isRequired": true
    }
  ],
  "labels": {
    "en": {
      "actionName": "Create Widget - Example 2",
      "actionCardContent": "Create widget {{widgetName}}",
      "inputFieldLabels": {
        "widgetName": "Widget Name"
      }
    }
  },
  "functions": [
    {
      "functionType": "PRE_ACTION_EXECUTION",
      "functionSource": "exports.main = function(event, callback) { return callback(transformRequest(event)); }\nfunction transformRequest(request) { return { webhookUrl: request.webhookUrl, body: JSON.stringify(request.fields), contentType: 'application/x-www-form-urlencoded', accept: 'application/json', httpMethod: 'POST' }; }"
    }
  ]
}

​
Defining a widget with dependencies and options from an external API

The following example sends data to create a new widget, with field dependencies and options that are fetched from an external API. In this example, because the widget size depends on the widget color, the user cannot input a value for the widget size until a widget color is chosen. The widget cost is also dependent on the widget color, but it is conditional on the value that the user selects for the widget color. Therefore, the user cannot input a value for the widget cost unless Red is selected as the widget color. 
{
  "actionUrl": "https://example.com/hubspot",
  "inputFields": [
    {
      "typeDefinition": {
        "name": "widgetName",
        "type": "string",
        "fieldType": "text"
      },
      "supportedValueTypes": ["STATIC_VALUE"],
      "isRequired": true
    },
    {
      "typeDefinition": {
        "name": "widgetColor",
        "type": "enumeration",
        "fieldType": "select",
        "options": [
          { "value": "red", "description": "red", "label": "Red" },
          { "value": "blue", "description": "blue", "label": "Blue" },
          { "value": "green", "description": "green", "label": "Green" }
        ]
      },
      "supportedValueTypes": ["STATIC_VALUE"]
    },
    {
      "typeDefinition": {
        "name": "widgetSize",
        "type": "enumeration",
        "fieldType": "select",
        "optionsUrl": "https://api.example.com/v1/widget-sizes"
      },
      "supportedValueTypes": ["STATIC_VALUE"]
    },
    {
      "typeDefinition": {
        "name": "widgetCost",
        "type": "number",
        "fieldType": "number"
      },
      "supportedValueTypes": ["OBJECT_PROPERTY"]
    }
  ],
  "inputFieldDependencies": [
    {
      "dependencyType": "SINGLE_FIELD",
      "controllingFieldName": "widgetColor",
      "dependentFieldNames": ["widgetSize"]
    },
    {
      "dependencyType": "CONDITIONAL_SINGLE_FIELD",
      "controllingFieldName": "widgetColor",
      "controllingFieldValue": "red",
      "dependentFieldNames": ["widgetCost"]
    }
  ],
  "labels": {
    "en": {
      "actionName": "Create Widget - Example 3",
      "actionCardContent": "Create widget {{widgetName}}",
      "inputFieldLabels": {
        "widgetName": "Widget Name",
        "widgetColor": "Widget Color",
        "widgetSize": "Widget Size",
        "widgetCost": "Widget Cost"
      }
    }
  },
  "objectTypes": ["CONTACT", "DEAL"],
  "functions": [
    {
      "functionType": "PRE_FETCH_OPTIONS",
      "id": "widgetSize",
      "functionSource": "exports.main = function(event, callback) { return callback(transformRequest(event)); }\nfunction transformRequest(request) { return { webhookUrl: request.webhookUrl + '?color=' + request.fields.widgetColor.value, body: JSON.stringify(request.fields), httpMethod: 'GET' }; }"
    }
  ]
}
Last modified on January 30, 2026