HubSpot Automation Actions V4
Browse all Hubspot APIs✓ Official Vendor SpecMarketingMarketing Automationoauth2, apiKey16 EndpointsREST
For Agents
Create custom workflow action definitions, attach execution functions, manage action revisions, and complete automation callbacks. Enables extending HubSpot workflows with external service integrations across 16 endpoints.
Use for: I need to create a custom workflow action for my HubSpot app, I want to attach a function to an automation action definition, List all custom action definitions for my app, Get the revision history for a specific action definition
Not supported: Does not handle workflow creation, contact record management, or email sending — use for custom workflow action definition, function attachment, and callback completion only.
Define and manage custom workflow actions that extend HubSpot's automation tool with external service integrations. Supports 16 endpoints for creating action definitions, attaching serverless functions to action steps, managing definition revisions, and completing workflow callbacks. Enables developers to build reusable automation actions that HubSpot users can configure within their workflows to call external services, process data, and return results back to the workflow execution context.
Install Jentic One Beta
Connect the Automation Actions V4 to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Automation Actions V4, 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 Automation Actions V4 API.
Define custom workflow actions with typed input fields, output properties, and execution functions that HubSpot users configure in the workflow editor
Attach serverless functions to action definitions that execute when a workflow reaches the custom action step
Complete single and batch workflow callbacks to return execution results back to the HubSpot workflow engine
Version action definitions with revision tracking to manage updates without breaking active workflows
Configure function types (pre-action, post-action, fetch) for different stages of the action execution lifecycle
Use Cases
Patterns agents use Automation Actions V4 API for, with concrete tasks.
★ AI Agent Workflow Extension Development
AI agents use the Automation Actions V4 API through Jentic to programmatically create and manage custom HubSpot workflow actions. The agent searches for 'create custom workflow action' via Jentic, receives the POST /automation/v4/actions/{appId} operation schema with required fields (actionUrl, published, labels, inputFields), and creates the action definition. This enables building custom integrations that HubSpot users drag into their workflows without the agent needing to navigate HubSpot's developer portal. Integration takes under an hour through Jentic versus 2-3 days for direct OAuth app setup and function deployment.
Create a new custom action definition for app ID 12345 with an input field 'email' of type string and an action URL pointing to the external service endpoint
Serverless Function Attachment
Attach execution functions to custom action definitions via PUT /automation/v4/actions/{appId}/{definitionId}/functions/{functionType}. Functions execute when a HubSpot workflow reaches the custom action step. The API supports multiple function types for different execution stages — pre-action validation, main execution, and post-action processing. Functions can be updated independently of the action definition, enabling iterative development without republishing the entire action.
Attach a POST_ACTION_EXECUTION function to action definition ID 'def-456' for app ID 12345, then verify the function was registered by retrieving it
Workflow Callback Completion
Complete workflow callbacks via POST /automation/v4/actions/callbacks/{callbackId}/complete when custom actions finish processing asynchronously. The callback returns output properties back to the HubSpot workflow engine, allowing subsequent workflow steps to use the custom action's results. Batch callback completion at /automation/v4/actions/callbacks/complete handles multiple concurrent workflow executions efficiently, critical for high-volume automation scenarios processing thousands of enrolled contacts.
Complete callback ID 'cb-789' with output properties including 'enriched_email' and 'score' values, then verify the callback was acknowledged
Action Definition Version Management
Track and retrieve action definition revisions via GET /automation/v4/actions/{appId}/{definitionId}/revisions. Each update to an action definition creates a new revision, enabling rollback and audit of changes. Active workflows reference specific revisions, so updating a definition creates a new version without disrupting running workflows. Revision history enables controlled deployment of action changes across production workflow environments.
Retrieve all revisions for action definition 'def-456' under app 12345, identify the latest revision ID, and compare its input fields to the previous version
Key Endpoints
16 endpoints — define and manage custom workflow actions that extend hubspot's automation tool with external service integrations.
METHOD
PATH
DESCRIPTION
POST
/automation/v4/actions/{appId}
Create a custom action definition
GET
/automation/v4/actions/{appId}
List all action definitions for an app
GET
/automation/v4/actions/{appId}/{definitionId}
Get a specific action definition
PATCH
/automation/v4/actions/{appId}/{definitionId}
Update an action definition
PUT
/automation/v4/actions/{appId}/{definitionId}/functions/{functionType}
Attach a function to an action
POST
/automation/v4/actions/callbacks/{callbackId}/complete
Complete a workflow callback
POST
/automation/v4/actions/callbacks/complete
Batch complete callbacks
GET
/automation/v4/actions/{appId}/{definitionId}/revisions
List action definition revisions
POST
/automation/v4/actions/{appId}
Create a custom action definition
GET
/automation/v4/actions/{appId}
List all action definitions for an app
GET
/automation/v4/actions/{appId}/{definitionId}
Get a specific action definition
PATCH
/automation/v4/actions/{appId}/{definitionId}
Update an action definition
PUT
/automation/v4/actions/{appId}/{definitionId}/functions/{functionType}
Attach a function to an action
POST
/automation/v4/actions/callbacks/{callbackId}/complete
Complete a workflow callback
POST
/automation/v4/actions/callbacks/complete
Batch complete callbacks
GET
/automation/v4/actions/{appId}/{definitionId}/revisions
List action definition revisions
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
HubSpot OAuth 2.0 tokens and developer API keys are stored encrypted in the Jentic vault (MAXsystem). Agents receive scoped access tokens with automatic refresh — raw OAuth secrets and hapikeys never enter the agent's context.
Intent-based discovery
Agents search by intent (e.g., 'create custom workflow action') and Jentic returns matching HubSpot Automation Actions operations with input schemas, so the agent can build workflow extensions without navigating HubSpot's developer documentation.
Time to first call
Direct HubSpot integration: 2-4 days for OAuth app registration, action definition schema design, 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 Automation Actions V4 API through Jentic.
What authentication does the HubSpot Automation Actions V4 API use?
The API supports OAuth 2.0 with the 'automation' scope for production apps and developer API keys (hapikey) for testing. OAuth tokens are obtained via HubSpot's authorization flow at https://app.hubspot.com/oauth/authorize. Through Jentic, OAuth tokens and developer keys are stored encrypted in the MAXsystem vault with automatic token refresh.
Can I create custom workflow actions with typed input fields?
Yes. POST to /automation/v4/actions/{appId} with a definition body containing inputFields array. Each input field specifies a typeDefinition (string, number, enumeration, etc.), label, and whether it's required. HubSpot users see these fields in the workflow editor when configuring your custom action step.
What are the rate limits for the HubSpot Automation Actions V4 API?
HubSpot enforces standard API rate limits: 100 requests per 10 seconds for OAuth apps and 500,000 requests per day. Batch callback completion at /automation/v4/actions/callbacks/complete processes multiple callbacks in a single request, reducing rate limit consumption for high-volume workflow executions.
How do I complete a workflow callback through Jentic?
Search Jentic for 'complete workflow automation callback' to find the POST /automation/v4/actions/callbacks/{callbackId}/complete operation. Provide the callbackId received when HubSpot invokes your action, along with output field values in the request body. Install with pip install jentic and use the search-load-execute flow.
What function types can I attach to custom actions?
The API supports multiple function types attached via PUT /automation/v4/actions/{appId}/{definitionId}/functions/{functionType}. Function types include PRE_ACTION_EXECUTION for validation before the action runs, POST_ACTION_EXECUTION for the main processing logic, and FETCH_OPTIONS for dynamically populating input field dropdown options in the workflow editor.
Can I version and roll back action definitions?
Yes. Every update to an action definition via PATCH /automation/v4/actions/{appId}/{definitionId} creates a new revision. Retrieve revision history via GET /automation/v4/actions/{appId}/{definitionId}/revisions and inspect any specific revision with GET /automation/v4/actions/{appId}/{definitionId}/revisions/{revisionId}. Active workflows reference specific revisions.
What HubSpot plan is required to use the Automation Actions V4 API?
Custom workflow actions require HubSpot Professional or Enterprise tier across Marketing, Sales, or Service Hubs. The API itself is available to any HubSpot developer app, but end users configuring the actions in workflows need the Professional tier or higher to access the workflow tool.
GET STARTED