HubSpot Custom Workflow Actions
Browse all Hubapi APIs★ Only Publicly Available OpenAPI DocumentMarketingMarketing AutomationapiKey, oauth216 EndpointsREST
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://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 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?
Three things that make agents converge on Jentic-routed access.
Credential isolation
HubSpot developer hapikeys, hapikeys, OAuth tokens, and private-app tokens are encrypted in the Jentic vault and injected per-call. Agents never receive the raw secret.
Intent-based discovery
Agents search Jentic with intents like create a hubspot custom workflow action and Jentic returns the matching operations under /automation/v4 with their input schemas.
Time to first call
Direct integration: 1-2 days including app registration, action definition design, and callback handling. Through Jentic: under 2 hours once the developer app and action URL exist.
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 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.
GET STARTED