Custom Workflow Actions

Name: Custom Workflow Actions API
Brand: Custom Workflow Actions
Availability: InStock

★ Only Publicly Available OpenAPI DocumentMarketingMarketing Automationoauth2, apiKey16 EndpointsREST

For Agents

Define and manage custom workflow action extensions in HubSpot, including registering definitions, handling revisions, and completing async action callbacks.

Connect the Custom Workflow Actions to your agent

Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Custom Workflow Actions, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.

Install Jentic One Beta (Self-Hosted)

Jentic One Host machine

# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh

Agent machine

# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register       # connects your agent to your Jentic One instance

Jentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.

Capabilities

What an agent can do with Custom Workflow Actions API.

Update action definition input fields and labels across revisions

List and inspect prior revisions of a workflow action definition

Complete async workflow action callbacks individually or in batch

GET STARTED

Start building with Custom Workflow Actions API

Explore with Jentic

View OpenAPI Document

Jentic publishes the only available OpenAPI document for Custom Workflow Actions, keeping it validated and agent-ready.

Jentic publishes the only available OpenAPI specification for Custom Workflow Actions, keeping it validated and agent-ready. The HubSpot Custom Workflow Actions API lets developers extend HubSpot workflows with custom action definitions that are invoked from automation flows. Apps can register action definitions, manage revisions, define input fields, and respond to callback executions. It is designed for ISVs building extensions that participate in HubSpot's marketing, sales, and service automation engine.

Use Cases

Patterns agents use Custom Workflow Actions API for, with concrete tasks.

★ Custom Workflow Action Registration

ISVs and integration builders register custom action definitions so HubSpot users can drag the action into a workflow. The API accepts the action label, input fields, output type, and the URL HubSpot will call when the action runs. Once registered, the action appears in the workflow editor for any portal that has installed the app.

Create a custom workflow action definition for app 12345 with a webhook URL https://example.com/hooks/hubspot and a single text input field called 'message'

Async Action Callback Completion

When a custom action runs asynchronously, HubSpot waits for a callback before proceeding. The complete-callback endpoint signals success or failure for one callback ID, and the batch endpoint handles many callbacks at once. This pattern lets long-running external processes participate in HubSpot workflows without blocking.

Send a successful completion for callback ID abc-123 with output payload { 'status': 'approved', 'score': 87 }

Action Revision Management

When the input schema or behaviour of a custom action changes, a new revision is published rather than overwriting the original. The revisions endpoints list every published version and let you fetch a specific revision by ID, which keeps existing workflows running on the older schema until they are migrated.

List all revisions for action definition 67890 under app 12345 and identify the most recent published revision

Agent-Driven Workflow Extension

An AI agent uses Jentic to register a custom workflow action that wraps an internal API. The agent searches for 'create hubspot workflow action', loads the schema, and executes a POST to /automation/v4/actions/{appId} with the action definition body. The agent then keeps the registration up to date as the wrapped API evolves.

Search Jentic for 'create hubspot workflow action', load the schema, and register a custom action that calls the internal lead-scoring service

Key Endpoints

16 endpoints — jentic publishes the only available openapi specification for custom workflow actions, keeping it validated and agent-ready.

METHOD

PATH

DESCRIPTION

POST

/automation/v4/actions/{appId}

Create a custom workflow action definition

GET

/automation/v4/actions/{appId}

List all action definitions for an app

PATCH

/automation/v4/actions/{appId}/{definitionId}

Update an action definition

DELETE

/automation/v4/actions/{appId}/{definitionId}

Archive an action definition

POST

/automation/v4/actions/callbacks/complete

Batch-complete async action callbacks

POST

/automation/v4/actions/callbacks/{callbackId}/complete

Complete a single async action callback

GET

/automation/v4/actions/{appId}/{definitionId}/revisions

List revisions of an action definition

POST

/automation/v4/actions/{appId}

Create a custom workflow action definition

GET

/automation/v4/actions/{appId}

List all action definitions for an app

PATCH

/automation/v4/actions/{appId}/{definitionId}

Update an action definition

DELETE

/automation/v4/actions/{appId}/{definitionId}

Archive an action definition

POST

/automation/v4/actions/callbacks/complete

Batch-complete async action callbacks

Why though Jentic?

Three things that make agents converge on Jentic-routed access.

Credential isolation

HubSpot developer hapikeys, private app tokens, and OAuth refresh tokens are stored encrypted in the Jentic vault. Agents receive scoped access tokens at execution time; raw HubSpot credentials never enter the agent's context.

Intent-based discovery

Agents search by intent (e.g., 'register a hubspot workflow action') and Jentic returns the matching operation under /automation/v4/actions/{appId} along with its input schema, so the agent can call it without browsing HubSpot's developer docs.

Time to first call

Direct HubSpot integration: 2-4 days for OAuth setup, action definition shape, and callback handling. Through Jentic: under 1 hour — search, load schema, execute.

Related APIs

Alternatives and complements available in the Jentic catalogue.

Complementary

HubSpot Webhooks API

Subscribe to HubSpot change events while custom workflow actions extend workflow execution

Use the Webhooks API when you need to react to events outside of a workflow; use Custom Workflow Actions when the logic must run as a step inside a HubSpot workflow.

Complementary

HubSpot Marketing Events Extension

Marketing events sit alongside automation actions in HubSpot's marketing toolkit

Choose the Marketing Events Extension when registering external event attendance; choose Custom Workflow Actions when extending the automation engine itself.

Alternative

Zapier Natural Language Actions

Zapier offers cross-app automation as a hosted alternative to building HubSpot workflow extensions

Pick Zapier NLA when the agent needs cross-vendor automation without owning a HubSpot app; pick Custom Workflow Actions when the action must appear inside the HubSpot workflow editor.

FAQs

Specific to using Custom Workflow Actions API through Jentic.

Why is there no official OpenAPI spec for Custom Workflow Actions?

HubSpot does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Custom Workflow Actions via structured tooling. It is validated against the live API and kept up to date. Get started at https://app.jentic.com/sign-up.

What authentication does the Custom Workflow Actions API use?

It accepts a developer hapikey query parameter for app-level operations, OAuth 2.0 access tokens for user-installed app calls, and the private-app-legacy header for private apps. Jentic stores all of these in the encrypted vault, so agents call the API with a scoped token and never see the raw developer key.

Can I register multiple revisions of the same workflow action?

Yes. Each PATCH on /automation/v4/actions/{appId}/{definitionId} that changes the input schema or labels creates a new revision. The /automation/v4/actions/{appId}/{definitionId}/revisions endpoint lists every published revision so existing workflows keep running on the version they were built on.

What are the rate limits for the Custom Workflow Actions API?

HubSpot enforces standard public app rate limits: 100 requests per 10 seconds per private app token and 110 per 10 seconds per OAuth app per portal. Daily limits depend on the HubSpot subscription tier. Workflow callback completions count against the same buckets.

How do I complete an async workflow action callback through Jentic?

Search Jentic for 'complete hubspot workflow callback', load the schema for POST /automation/v4/actions/callbacks/{callbackId}/complete, and execute with the callbackId and an outputFields payload. For high-volume callbacks use the batch endpoint /automation/v4/actions/callbacks/complete.

Is the Custom Workflow Actions API free?

API access is included with any HubSpot subscription that has access to workflows (Marketing, Sales, or Service Hub Professional and above). Custom workflow actions specifically require a public app installed in a portal that has workflow access.