canonical: https://jentic.com/apis/hubapi.com/hubspot-automation-api

# HubSpot Custom Workflow Actions

Jentic publishes the only available OpenAPI specification for Custom Workflow Actions, keeping it validated and agent-ready. The HubSpot Custom Workflow Actions API lets developers extend HubSpot workflows with custom action definitions that are invoked from automation flows. Apps can register action definitions, manage revisions, define input fields, and respond to callback executions. It is designed for ISVs building extensions that participate in HubSpot's marketing, sales, and service automation engine.

## For AI agents

Define and manage custom workflow action extensions in HubSpot, including registering definitions, handling revisions, and completing async action callbacks.

## Scope

Does not handle CRM record CRUD, marketing email sends, or contact lists - use for registering and operating custom workflow action extensions only.

## Capabilities

- Register custom workflow action definitions for a HubSpot app
- Update action definition input fields and labels across revisions
- List and inspect prior revisions of a workflow action definition
- Complete async workflow action callbacks individually or in batch
- Configure callable functions tied to action definitions by function type
- Delete obsolete workflow action definitions for an installed app

## Use cases

### Custom Workflow Action Registration

ISVs and integration builders register custom action definitions so HubSpot users can drag the action into a workflow. The API accepts the action label, input fields, output type, and the URL HubSpot will call when the action runs. Once registered, the action appears in the workflow editor for any portal that has installed the app.

Example prompt: Create a custom workflow action definition for app 12345 with a webhook URL https://example.com/hooks/hubspot and a single text input field called 'message'

### Async Action Callback Completion

When a custom action runs asynchronously, HubSpot waits for a callback before proceeding. The complete-callback endpoint signals success or failure for one callback ID, and the batch endpoint handles many callbacks at once. This pattern lets long-running external processes participate in HubSpot workflows without blocking.

Example prompt: Send a successful completion for callback ID abc-123 with output payload { 'status': 'approved', 'score': 87 }

### Action Revision Management

When the input schema or behaviour of a custom action changes, a new revision is published rather than overwriting the original. The revisions endpoints list every published version and let you fetch a specific revision by ID, which keeps existing workflows running on the older schema until they are migrated.

Example prompt: List all revisions for action definition 67890 under app 12345 and identify the most recent published revision

### Agent-Driven Workflow Extension

An AI agent uses Jentic to register a custom workflow action that wraps an internal API. The agent searches for 'create hubspot workflow action', loads the schema, and executes a POST to /automation/v4/actions/{appId} with the action definition body. The agent then keeps the registration up to date as the wrapped API evolves.

Example prompt: Search Jentic for 'create hubspot workflow action', load the schema, and register a custom action that calls the internal lead-scoring service

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /automation/v4/actions/{appId} | Create a custom workflow action definition |
| GET | /automation/v4/actions/{appId} | List all action definitions for an app |
| PATCH | /automation/v4/actions/{appId}/{definitionId} | Update an action definition |
| DELETE | /automation/v4/actions/{appId}/{definitionId} | Archive an action definition |
| POST | /automation/v4/actions/callbacks/complete | Batch-complete async action callbacks |
| POST | /automation/v4/actions/callbacks/{callbackId}/complete | Complete a single async action callback |
| GET | /automation/v4/actions/{appId}/{definitionId}/revisions | List revisions of an action definition |

## Key resources

- **Action Definitions** — Create, list, update, and delete custom workflow action definitions for a HubSpot app
- **Revisions** — List and fetch published revisions of a workflow action definition
- **Callbacks** — Complete async workflow action callbacks individually or in batch
- **Functions** — Manage the callable functions tied to an action definition

## Why Jentic

- **Setup:** Wiring HubSpot Custom Workflow Actions by hand means handling both OAuth and app-token auth, tracking the app and definition ids across api.hubapi.com, and managing callback completion 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:** HubSpot puts the app id in the URL path (/automation/v4/actions/{appId}), so a rule can pin your agent to one app: it registers and reads workflow action definitions for that app and nothing else. You choose the operations it may call, so destructive ones like PATCH or DELETE on a definition are not included unless you add them.
- **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 'register a hubspot 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 Webhooks API** — Subscribe to HubSpot change events while custom workflow actions extend workflow execution
- **HubSpot Marketing Events Extension** — Marketing events sit alongside automation actions in HubSpot's marketing toolkit
- **Zapier Natural Language Actions** — Zapier offers cross-app automation as a hosted alternative to building HubSpot workflow extensions

## 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 the Custom Workflow Actions API use?

It accepts a developer hapikey query parameter for app-level operations, OAuth 2.0 access tokens for user-installed app calls, and the private-app-legacy header for private apps. Jentic stores all of these in the encrypted vault, so agents call the API with a scoped token and never see the raw developer key.

### Can I register multiple revisions of the same workflow action?

Yes. Each PATCH on /automation/v4/actions/{appId}/{definitionId} that changes the input schema or labels creates a new revision. The /automation/v4/actions/{appId}/{definitionId}/revisions endpoint lists every published revision so existing workflows keep running on the version they were built on.

### What are the rate limits for the Custom Workflow Actions API?

HubSpot enforces standard public app rate limits: 100 requests per 10 seconds per private app token and 110 per 10 seconds per OAuth app per portal. Daily limits depend on the HubSpot subscription tier. Workflow callback completions count against the same buckets.

### How do I complete an async workflow action callback through Jentic?

Search Jentic for 'complete hubspot workflow callback', load the schema for POST /automation/v4/actions/callbacks/{callbackId}/complete, and execute with the callbackId and an outputFields payload. For high-volume callbacks use the batch endpoint /automation/v4/actions/callbacks/complete.

### Is the Custom Workflow Actions API free?

API access is included with any HubSpot subscription that has access to workflows (Marketing, Sales, or Service Hub Professional and above). Custom workflow actions specifically require a public app installed in a portal that has workflow access.

### 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. Since HubSpot puts the app id in the URL path (/automation/v4/actions/{appId}), you can pin the agent to a single app so it only registers and reads that app's workflow action definitions. You also choose the exact operations it may call, so destructive ones like PATCH or DELETE on a definition, or callback completions, are excluded unless you add them.