canonical: https://jentic.com/apis/hubapi.com/hubspot-custom-workflow-actions

# HubSpot Custom Workflow Actions

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.

## For AI agents

Register, update, and version custom workflow action blocks for HubSpot apps, plus complete callbacks from long-running action functions.

## Scope

Does not create workflows, send marketing emails, or manage contacts - use only for registering and managing custom action blocks that workflows can call.

## Capabilities

- 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

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

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

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

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

Example prompt: Search Jentic for create a hubspot custom workflow action, load POST /automation/v4/actions/{appId}, and execute with the action definition payload.

## Key endpoints

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

## Key resources

- **Definitions** — Create, list, get, update, and archive custom action definitions
- **Functions** — Attach or replace serverless functions associated with an action
- **Callbacks** — Complete single or batched callbacks for long-running action steps
- **Revisions** — Inspect revision history of an action definition

## Why Jentic

- **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 handling:** 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.
- **Discovery method:** 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

- **HubSpot Automation API** — Manage HubSpot workflows themselves, where custom actions are dropped in as steps
- **HubSpot Webhooks API** — React to HubSpot events asynchronously rather than authoring drop-in workflow steps
- **HubSpot Marketing API** — Marketing assets - emails, lists, campaigns - that custom workflow actions often interact with

## FAQ

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