canonical: https://jentic.com/apis/hubspot.com/hubspot-automation-actions-v4

# HubSpot Automation Actions V4

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.

## For AI 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.

## Scope

Does not handle workflow creation, contact record management, or email sending - use for custom workflow action definition, function attachment, and callback completion only.

## Capabilities

- 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

### 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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

| 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 |

## Key resources

- **Action Definitions** — Create, update, and manage custom workflow action definitions with input fields and output properties
- **Functions** — Attach and manage serverless execution functions for different action lifecycle stages
- **Callbacks** — Complete single and batch workflow callbacks to return results to the workflow engine
- **Revisions** — Track version history of action definitions for audit and rollback

## Why Jentic

- **Setup:** Wiring HubSpot Automation Actions V4 by hand means handling both OAuth and app-token auth, tracking app and definition ids across api.hubapi.com, and attaching functions and completing callbacks yourself. Through Jentic you install once, import Automation Actions V4 from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** HubSpot puts the app id in the URL path (/automation/v4/actions/{appId}), so a rule can pin your agent to one app: it defines and reads workflow actions for that app and nothing else. You choose the operations it may call, so a function replacement with PUT or a DELETE on a definition is not included unless you add it.
- **Credential handling:** Your HubSpot credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a custom workflow action', and Jentic returns the matching operation under /automation/v4/actions/{appId} with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **HubSpot Automation V4** — Core workflow automation engine that orchestrates the workflows custom actions plug into
- **HubSpot CRM Contacts** — Contact data that workflows enroll and custom actions process
- **HubSpot Webhooks** — Event-driven notifications for CRM changes that can trigger external workflow processing
- **Zapier NLA** — No-code automation platform connecting HubSpot to external services without custom action development
- **n8n API** — Self-hosted workflow automation platform with visual editor and custom node development

## FAQ

### 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 your Jentic One instance 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.

### Can I limit what my agent is allowed to do with the HubSpot Automation Actions V4 API?

Yes. Because Jentic One is self-hosted by you, your own rules decide which operations and credentials the agent may use. HubSpot carries 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 define and read workflow actions for that app and nothing else. You also choose which operations it may call, so a function replacement with PUT or a DELETE on a definition stays out of reach unless you explicitly grant it.