Actions

The ballerinax/hubspot.automation.actions package exposes the following clients:

Client	Purpose
`Client`	Manages HubSpot custom workflow extension definitions, functions, revisions, and callback completions.

Client

Manages HubSpot custom workflow extension definitions, functions, revisions, and callback completions.

Configuration

Field	Type	Default	Description
`auth`	`http:BearerTokenConfig\|OAuth2RefreshTokenGrantConfig\|ApiKeysConfig`	Required	Authentication configuration. Use OAuth 2.0 or bearer token for callback endpoints, or `ApiKeysConfig` with a developer API key for definition/function/revision endpoints.
`httpVersion`	`HttpVersion`	`HTTP_2_0`	HTTP protocol version.
`timeout`	`decimal`	`30`	Request timeout in seconds.
`retryConfig`	`RetryConfig`	`()`	Retry configuration for failed requests.
`secureSocket`	`ClientSecureSocket`	`()`	SSL/TLS configuration.
`proxy`	`ProxyConfig`	`()`	Proxy server configuration.
`validation`	`boolean`	`true`	Enable or disable payload validation.

Initializing the client

import ballerinax/hubspot.automation.actions as hubspotAutomation;

configurable string apiKey = ?;

hubspotAutomation:Client hubspotClient = check new ({
    auth: {
        hapikey: apiKey,
        privateAppLegacy: ""
    }
});

Operations

Extension definitions

Get paged extension definitions

Retrieves a paginated list of extension definitions for the specified app.

Parameters:

Name	Type	Required	Description
`appId`	`int:Signed32`	Yes	The HubSpot app ID.
`limit`	`int`	No	Maximum number of results per page.
`after`	`string`	No	Cursor token for the next page of results.
`archived`	`boolean`	No	Whether to include archived definitions. Defaults to `false`.

Returns: CollectionResponsePublicActionDefinitionForwardPaging|error

Sample code:

CollectionResponsePublicActionDefinitionForwardPaging response =
    check hubspotClient->/[appId].get();

Sample response:

{
  "results": [
    {
      "id": "12345",
      "revisionId": "1",
      "actionUrl": "https://example.com/action",
      "published": true,
      "labels": {
        "actionName": "My Custom Action",
        "actionDescription": "Performs a custom operation"
      },
      "inputFields": [],
      "functions": [],
      "objectTypes": ["CONTACT"]
    }
  ],
  "paging": {
    "next": {
      "after": "abc123"
    }
  }
}

Create a new extension definition

Creates a new custom workflow extension definition for the specified app.

Parameters:

Name	Type	Required	Description
`appId`	`int:Signed32`	Yes	The HubSpot app ID.
`payload`	`PublicActionDefinitionEgg`	Yes	The extension definition to create, including labels, input fields, functions, and object types.

Returns: PublicActionDefinition|error

Sample code:

hubspotAutomation:FieldTypeDefinition fieldType = {
    name: "staticInput",
    'type: "string",
    fieldType: "text",
    label: "Static Input",
    description: "A simple text input",
    options: [],
    externalOptions: false
};

hubspotAutomation:InputFieldDefinition inputField = {
    isRequired: true,
    automationFieldType: "test_automation_field",
    typeDefinition: fieldType,
    supportedValueTypes: ["STATIC_VALUE"]
};

hubspotAutomation:PublicActionFunction actionFunction = {
    functionSource: "exports.main = (event, callback) => { callback({ outputFields: {} }); }",
    functionType: "PRE_ACTION_EXECUTION"
};

hubspotAutomation:PublicActionDefinitionEgg extensionDef = {
    actionUrl: "https://example.com/action",
    published: false,
    objectTypes: ["CONTACT"],
    labels: {},
    inputFields: [inputField],
    functions: [actionFunction]
};

hubspotAutomation:PublicActionDefinition result =
    check hubspotClient->/[appId].post(extensionDef);

Sample response:

{
  "id": "67890",
  "revisionId": "1",
  "actionUrl": "https://example.com/action",
  "published": false,
  "labels": {},
  "inputFields": [
    {
      "isRequired": true,
      "automationFieldType": "test_automation_field",
      "typeDefinition": {
        "name": "staticInput",
        "type": "string",
        "fieldType": "text",
        "label": "Static Input",
        "options": [],
        "externalOptions": false
      },
      "supportedValueTypes": ["STATIC_VALUE"]
    }
  ],
  "functions": [
    {
      "functionType": "PRE_ACTION_EXECUTION",
      "id": "func_001"
    }
  ],
  "objectTypes": ["CONTACT"]
}

Get extension definition by ID

Retrieves a single extension definition by its app ID and definition ID.

Parameters:

Name	Type	Required	Description
`appId`	`int:Signed32`	Yes	The HubSpot app ID.
`definitionId`	`string`	Yes	The extension definition ID.
`archived`	`boolean`	No	Whether to return archived definitions. Defaults to `false`.

Returns: PublicActionDefinition|error

Sample code:

hubspotAutomation:PublicActionDefinition definition =
    check hubspotClient->/[appId]/[definitionId].get();

Sample response:

{
  "id": "67890",
  "revisionId": "1",
  "actionUrl": "https://example.com/action",
  "published": false,
  "labels": {
    "actionName": "My Custom Action"
  },
  "inputFields": [],
  "functions": [],
  "objectTypes": ["CONTACT"]
}

Patch an existing extension definition

Partially updates an existing extension definition.

Parameters:

Name	Type	Required	Description
`appId`	`int:Signed32`	Yes	The HubSpot app ID.
`definitionId`	`string`	Yes	The extension definition ID.
`payload`	`PublicActionDefinitionPatch`	Yes	Fields to update on the extension definition.

Returns: PublicActionDefinition|error

Sample code:

hubspotAutomation:PublicActionDefinition updated =
    check hubspotClient->/[appId]/[definitionId].patch({
        actionUrl: "https://example.com/updated-action",
        labels: {
            actionName: "Updated Action Name"
        }
    });

Sample response:

{
  "id": "67890",
  "revisionId": "2",
  "actionUrl": "https://example.com/updated-action",
  "published": false,
  "labels": {
    "actionName": "Updated Action Name"
  },
  "inputFields": [],
  "functions": [],
  "objectTypes": ["CONTACT"]
}

Archive an extension definition

Archives (soft-deletes) an extension definition by its app ID and definition ID.

Parameters:

Name	Type	Required	Description
`appId`	`int:Signed32`	Yes	The HubSpot app ID.
`definitionId`	`string`	Yes	The extension definition ID.

Returns: error?

Sample code:

check hubspotClient->/[appId]/[definitionId].delete();

Custom functions

Get all functions for a definition

Retrieves all custom functions associated with an extension definition.

Parameters:

Name	Type	Required	Description
`appId`	`int:Signed32`	Yes	The HubSpot app ID.
`definitionId`	`string`	Yes	The extension definition ID.

Returns: CollectionResponsePublicActionFunctionIdentifierNoPaging|error

Sample code:

CollectionResponsePublicActionFunctionIdentifierNoPaging functions =
    check hubspotClient->/[appId]/[definitionId]/functions.get();

Sample response:

{
  "results": [
    {
      "functionType": "PRE_ACTION_EXECUTION",
      "id": "func_001"
    },
    {
      "functionType": "POST_ACTION_EXECUTION",
      "id": "func_002"
    }
  ]
}

Get function by type

Retrieves a function by its type for the specified extension definition.

Parameters:

Name	Type	Required	Description
`appId`	`int:Signed32`	Yes	The HubSpot app ID.
`definitionId`	`string`	Yes	The extension definition ID.
`functionType`	`"PRE_ACTION_EXECUTION"\|"PRE_FETCH_OPTIONS"\|"POST_FETCH_OPTIONS"\|"POST_ACTION_EXECUTION"`	Yes	The function type to retrieve.

Returns: PublicActionFunction|error

Sample code:

hubspotAutomation:PublicActionFunction fn =
    check hubspotClient->/[appId]/[definitionId]/functions/["PRE_ACTION_EXECUTION"].get();

Sample response:

{
  "functionSource": "exports.main = (event, callback) => { callback({ outputFields: {} }); }",
  "functionType": "PRE_ACTION_EXECUTION",
  "id": "func_001"
}

Insert or replace a function by type

Inserts a new function or replaces an existing one for the given type.

Parameters:

Name	Type	Required	Description
`appId`	`int:Signed32`	Yes	The HubSpot app ID.
`definitionId`	`string`	Yes	The extension definition ID.
`functionType`	`"PRE_ACTION_EXECUTION"\|"PRE_FETCH_OPTIONS"\|"POST_FETCH_OPTIONS"\|"POST_ACTION_EXECUTION"`	Yes	The function type to set.
`payload`	`string`	Yes	The function source code as plain text.

Returns: PublicActionFunctionIdentifier|error

Sample code:

hubspotAutomation:PublicActionFunctionIdentifier result =
    check hubspotClient->/[appId]/[definitionId]/functions/["PRE_ACTION_EXECUTION"]
        .put("exports.main = (event, callback) => { callback({ outputFields: {} }); }");

Sample response:

{
  "functionType": "PRE_ACTION_EXECUTION",
  "id": "func_001"
}

Delete a function by type

Archives a function by its type for the specified extension definition.

Parameters:

Name	Type	Required	Description
`appId`	`int:Signed32`	Yes	The HubSpot app ID.
`definitionId`	`string`	Yes	The extension definition ID.
`functionType`	`"PRE_ACTION_EXECUTION"\|"PRE_FETCH_OPTIONS"\|"POST_FETCH_OPTIONS"\|"POST_ACTION_EXECUTION"`	Yes	The function type to delete.

Returns: error?

Sample code:

check hubspotClient->/[appId]/[definitionId]/functions/["PRE_ACTION_EXECUTION"].delete();

Get a specific function by type and ID

Retrieves a specific function by its type and unique function ID.

Parameters:

Name	Type	Required	Description
`appId`	`int:Signed32`	Yes	The HubSpot app ID.
`definitionId`	`string`	Yes	The extension definition ID.
`functionType`	`"PRE_ACTION_EXECUTION"\|"PRE_FETCH_OPTIONS"\|"POST_FETCH_OPTIONS"\|"POST_ACTION_EXECUTION"`	Yes	The function type.
`functionId`	`string`	Yes	The unique function ID.

Returns: PublicActionFunction|error

Sample code:

hubspotAutomation:PublicActionFunction fn =
    check hubspotClient->/[appId]/[definitionId]/functions/["PRE_ACTION_EXECUTION"]/[functionId].get();

Sample response:

{
  "functionSource": "exports.main = (event, callback) => { callback({ outputFields: {} }); }",
  "functionType": "PRE_ACTION_EXECUTION",
  "id": "func_001"
}

Insert or replace a specific function by type and ID

Inserts a new function or replaces an existing one identified by type and function ID.

Parameters:

Name	Type	Required	Description
`appId`	`int:Signed32`	Yes	The HubSpot app ID.
`definitionId`	`string`	Yes	The extension definition ID.
`functionType`	`"PRE_ACTION_EXECUTION"\|"PRE_FETCH_OPTIONS"\|"POST_FETCH_OPTIONS"\|"POST_ACTION_EXECUTION"`	Yes	The function type.
`functionId`	`string`	Yes	The unique function ID.
`payload`	`string`	Yes	The function source code as plain text.

Returns: PublicActionFunctionIdentifier|error

Sample code:

hubspotAutomation:PublicActionFunctionIdentifier result =
    check hubspotClient->/[appId]/[definitionId]/functions/["POST_ACTION_EXECUTION"]/[functionId]
        .put("exports.main = (event, callback) => { callback({ outputFields: { status: 'done' } }); }");

Sample response:

{
  "functionType": "POST_ACTION_EXECUTION",
  "id": "func_003"
}

Delete a specific function by type and ID

Archives a specific function identified by its type and function ID.

Parameters:

Name	Type	Required	Description
`appId`	`int:Signed32`	Yes	The HubSpot app ID.
`definitionId`	`string`	Yes	The extension definition ID.
`functionType`	`"PRE_ACTION_EXECUTION"\|"PRE_FETCH_OPTIONS"\|"POST_FETCH_OPTIONS"\|"POST_ACTION_EXECUTION"`	Yes	The function type.
`functionId`	`string`	Yes	The unique function ID.

Returns: error?

Sample code:

check hubspotClient->/[appId]/[definitionId]/functions/["POST_ACTION_EXECUTION"]/[functionId].delete();

Revisions

Get all revisions for a definition

Retrieves a paginated list of all revisions for an extension definition.

Parameters:

Name	Type	Required	Description
`appId`	`int:Signed32`	Yes	The HubSpot app ID.
`definitionId`	`string`	Yes	The extension definition ID.
`limit`	`int`	No	Maximum number of results per page.
`after`	`string`	No	Cursor token for the next page of results.

Returns: CollectionResponsePublicActionRevisionForwardPaging|error

Sample code:

CollectionResponsePublicActionRevisionForwardPaging revisions =
    check hubspotClient->/[appId]/[definitionId]/revisions.get();

Sample response:

{
  "results": [
    {
      "revisionId": "2",
      "createdAt": "2025-01-15T10:30:00Z",
      "id": "rev_002",
      "definition": {
        "id": "67890",
        "revisionId": "2",
        "actionUrl": "https://example.com/updated-action",
        "published": true,
        "labels": {"actionName": "My Action"},
        "inputFields": [],
        "functions": [],
        "objectTypes": ["CONTACT"]
      }
    }
  ],
  "paging": {}
}

Get a specific revision by ID

Retrieves a specific revision of an extension definition.

Parameters:

Name	Type	Required	Description
`appId`	`int:Signed32`	Yes	The HubSpot app ID.
`definitionId`	`string`	Yes	The extension definition ID.
`revisionId`	`string`	Yes	The revision ID.

Returns: PublicActionRevision|error

Sample code:

hubspotAutomation:PublicActionRevision revision =
    check hubspotClient->/[appId]/[definitionId]/revisions/[revisionId].get();

Sample response:

{
  "revisionId": "1",
  "createdAt": "2025-01-10T08:00:00Z",
  "id": "rev_001",
  "definition": {
    "id": "67890",
    "revisionId": "1",
    "actionUrl": "https://example.com/action",
    "published": false,
    "labels": {"actionName": "My Action"},
    "inputFields": [],
    "functions": [],
    "objectTypes": ["CONTACT"]
  }
}

Callbacks

Complete a single callback

Completes a single workflow callback, returning output fields to the HubSpot workflow.

Parameters:

Name	Type	Required	Description
`callbackId`	`string`	Yes	The callback ID provided by HubSpot when the workflow action is triggered.
`payload`	`CallbackCompletionRequest`	Yes	The completion request containing output field values.

Returns: error?

Sample code:

check hubspotClient->/callbacks/[callbackId]/complete.post({
    outputFields: {
        "status": "completed",
        "result": "success"
    }
});

Complete a batch of callbacks

Completes multiple workflow callbacks in a single batch request.

Parameters:

Name	Type	Required	Description
`payload`	`BatchInputCallbackCompletionBatchRequest`	Yes	Batch request containing an array of callback completion entries, each with a `callbackId` and `outputFields`.

Returns: error?

Sample code:

hubspotAutomation:BatchInputCallbackCompletionBatchRequest batchRequest = {
    inputs: [
        {
            callbackId: "callback_001",
            outputFields: {"status": "completed"}
        },
        {
            callbackId: "callback_002",
            outputFields: {"status": "completed"}
        }
    ]
};

check hubspotClient->/callbacks/complete.post(batchRequest);

Client​

Configuration​

Initializing the client​

Operations​

Extension definitions​

Custom functions​

Revisions​

Callbacks​

Client

Configuration

Initializing the client

Operations

Extension definitions

Custom functions

Revisions

Callbacks