HubSpot Custom Workflow Actions
Browse all Hubapi APIs★ 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.
Use for: I need to register a new custom workflow action for my HubSpot app, I want to complete a pending workflow action callback, List all revisions of a workflow action definition, Retrieve the input field schema for a workflow action
Not supported: Does not handle CRM record CRUD, marketing email sends, or contact lists — use for registering and operating custom workflow action extensions only.
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.
Install Jentic One Beta
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.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: 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 | sh2
Step 2: 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 instanceJentic 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.
Register custom workflow action definitions for a HubSpot app
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
Configure callable functions tied to action definitions by function type
Delete obsolete workflow action definitions for an installed app
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
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
Why 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.
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.
GET STARTED