HubSpot Custom Workflow Actions
Browse all Hubapi APIsAgent-ready OpenAPI document · curated by JenticMarketingMarketing AutomationapiKey, oauth216 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Register, update, and version custom workflow action blocks for HubSpot apps, plus complete callbacks from long-running action functions.
Use for: I need to register a new custom workflow action, Update the input field config on an existing custom action, Complete a HubSpot workflow callback for my long-running step, List all custom actions registered for app 12345
Not supported: Does not create workflows, send marketing emails, or manage contacts - use only for registering and managing custom action blocks that workflows can call.
Jentic publishes the only available OpenAPI specification for Custom Workflow Actions, keeping it validated and agent-ready. HubSpot Custom Workflow Actions let app developers register their own action blocks that appear in the HubSpot workflow builder, so customers can drop a third-party step (send a message, create an order, run a calculation) into a marketing or operations workflow. The API covers action definitions, function code attached to each action, callbacks for long-running steps, and revision history for safe rollouts.
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://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhubapi.com%2Fhubspot-custom-workflow-actions" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhubapi.com%2Fhubspot-custom-workflow-actions" | 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 a new custom workflow action for an app via POST /automation/v4/actions/{appId}
List, retrieve, update, and archive custom action definitions per app
Attach or replace serverless functions to an action with PUT /automation/v4/actions/{appId}/{definitionId}/functions/{functionType}
Complete a single long-running callback with POST /automation/v4/actions/callbacks/{callbackId}/complete
Complete a batch of callbacks in one call via POST /automation/v4/actions/callbacks/complete
Inspect action revision history and roll forward via the revisions endpoints
Use Cases
Patterns agents use Custom Workflow Actions API for, with concrete tasks.
★ Add Third-Party Steps to HubSpot Workflows
Expose actions like send-slack-message or create-shipment as drag-and-drop steps in the HubSpot workflow builder. POST /automation/v4/actions/{appId} registers the action; HubSpot then surfaces it in the customer's workflow editor where it can be parameterised per workflow.
POST a new action to /automation/v4/actions/12345 with actionUrl, inputFields, and labels for the workflow builder UI.
Run Long Operations via Callbacks
Handle steps that need more than a few seconds - provisioning a tenant, generating a PDF - by accepting the action call and returning a callback ID. When work finishes, complete the step with POST /automation/v4/actions/callbacks/{callbackId}/complete so the workflow advances.
POST to /automation/v4/actions/callbacks/{callbackId}/complete with the callback ID and outputFields once the async job finishes.
Version and Roll Out Action Updates Safely
Use the revisions endpoints to inspect prior versions of an action and update its inputs without breaking workflows that already reference it. PATCH /automation/v4/actions/{appId}/{definitionId} stores a new revision and GET /automation/v4/actions/{appId}/{definitionId}/revisions lists them.
GET the revisions list for definitionId 8472 and confirm a new revision was created after the latest PATCH update.
AI Agent Workflow Action Provisioning via Jentic
An AI agent shipping a HubSpot integration calls Jentic to provision new custom workflow actions and complete callbacks programmatically - without browsing the HubSpot developer docs or wiring auth manually.
Search Jentic for create a hubspot custom workflow action, load POST /automation/v4/actions/{appId}, and execute with the action definition payload.
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}
Register a new custom workflow action
GET
/automation/v4/actions/{appId}
List all custom actions for an app
PATCH
/automation/v4/actions/{appId}/{definitionId}
Update a custom action definition
DELETE
/automation/v4/actions/{appId}/{definitionId}
Archive a custom action
PUT
/automation/v4/actions/{appId}/{definitionId}/functions/{functionType}
Create or replace an action function
POST
/automation/v4/actions/callbacks/{callbackId}/complete
Complete a single workflow callback
POST
/automation/v4/actions/callbacks/complete
Complete a batch of workflow callbacks
GET
/automation/v4/actions/{appId}/{definitionId}/revisions
List revisions for a custom action
POST
/automation/v4/actions/{appId}
Register a new custom workflow action
GET
/automation/v4/actions/{appId}
List all custom actions for an app
PATCH
/automation/v4/actions/{appId}/{definitionId}
Update a custom action definition
DELETE
/automation/v4/actions/{appId}/{definitionId}
Archive a custom action
PUT
/automation/v4/actions/{appId}/{definitionId}/functions/{functionType}
Create or replace an action function
POST
/automation/v4/actions/callbacks/{callbackId}/complete
Complete a single workflow callback
POST
/automation/v4/actions/callbacks/complete
Complete a batch of workflow callbacks
GET
/automation/v4/actions/{appId}/{definitionId}/revisions
List revisions for a custom action
Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring HubSpot custom workflow actions by hand means choosing between its hapikey query, OAuth, and private-app auth, keeping the api.hubapi.com host straight across the automation v4 endpoints, and handling errors yourself. Through Jentic you install once, import Custom Workflow Actions from the API Directory, store the credential once, and your agent calls it.
Permission scoping
Custom Workflow Actions puts the app id in the URL path (/automation/v4/actions/{appId}), so a rule can pin your agent to one app: it can create and read action definitions for that app and nothing else. You choose the operations it may call, so patching or deleting definitions is not included unless you add them.
Credential isolation
Your HubSpot credential is stored once, encrypted, by your own Jentic One instance and injected per call at execution time. It never enters the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'create a HubSpot custom workflow action' or 'list action definitions', and Jentic returns the matching operation under /automation/v4 with its input schema so the agent calls the right endpoint without browsing the reference docs.
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 with Jentic One, the self-hosted execution layer.
What authentication does Custom Workflow Actions use?
The API supports a developer hapikey query parameter, regular hapikey, OAuth 2.0 authorization code with the automation scope, and the private-app-legacy header. Through Jentic, whichever credential is configured is held encrypted in the vault and injected per-call.
Can my action take longer than a few seconds to run?
Yes. Return a callbackId from the action call instead of completing inline, then call POST /automation/v4/actions/callbacks/{callbackId}/complete (or the batch variant) once the work finishes. HubSpot pauses the workflow on that step until the callback completes.
What are the rate limits for Custom Workflow Actions?
Custom workflow action management is governed by the standard developer-key rate limits (typically 100 requests / 10 seconds for hapikey, higher for OAuth on Enterprise). Action invocations themselves are bounded by HubSpot's workflow execution throughput.
How do I register a new custom action through Jentic?
Search Jentic for create a hubspot custom workflow action, load POST /automation/v4/actions/{appId}, and execute with the action's actionUrl, inputFields schema, output schema, and UI labels. Jentic injects the developer hapikey from the vault.
How do I batch-complete pending callbacks?
POST to /automation/v4/actions/callbacks/complete with an array of {callbackId, outputFields} entries. This is the most efficient path when many parallel workflow instances are waiting on the same kind of asynchronous job.
Can I limit what my agent is allowed to do with the Custom Workflow Actions API?
Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use. Custom Workflow Actions puts the app id in the URL path (/automation/v4/actions/{appId}), so you can pin the agent to a single app and let it only create and read action definitions there. Since you pick the exact operations it can call, patching or deleting definitions and completing callbacks stay off limits until you explicitly grant them.
GET STARTED