HubSpot Automation Actions V4 API patterns for creating custom workflow actions, action functions, and callback handling.
From opspal-hubspotnpx claudepluginhub revpalsfdc/opspal-commercial --plugin opspal-hubspotThis skill uses the workspace's default tool permissions.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Executes pre-written implementation plans: critically reviews, follows bite-sized steps exactly, runs verifications, tracks progress with checkpoints, uses git worktrees, stops on blockers.
Comprehensive knowledge base for creating custom workflow actions via HubSpot's Automation Actions V4 API.
| Document | Purpose |
|---|---|
action-patterns.md | Common action patterns and templates |
function-reference.md | Action function types and examples |
callback-handling.md | Callback completion and state management |
| Task | Route To |
|---|---|
| Create custom workflow action | hubspot-custom-action-builder |
| Build workflows using actions | hubspot-workflow-builder |
| Complete workflow callbacks | hubspot-callback-orchestrator |
| Create HubSpot apps | hubspot-app-developer |
| Deploy serverless functions | hubspot-cms-theme-manager |
| Scenario | Use Custom Action | Use Built-in Action |
|---|---|---|
| External API integration | Yes | No |
| Third-party service calls | Yes | No |
| Complex business logic | Yes | Maybe |
| Simple property updates | No | Yes |
| Email sending | No | Yes (native) |
| Internal HubSpot operations | No | Yes |
| Endpoint | Method | Purpose |
|---|---|---|
/automation/v4/actions/{appId} | POST | Create action |
/automation/v4/actions/{appId} | GET | List actions |
/automation/v4/actions/{appId}/{definitionId} | GET | Get action |
/automation/v4/actions/{appId}/{definitionId} | PATCH | Update action |
/automation/v4/actions/{appId}/{definitionId} | DELETE | Delete action |
/automation/v4/actions/{appId}/{definitionId}/functions/{functionType} | PUT | Add function |
/automation/v4/actions/{appId}/{definitionId}/functions/{functionType} | DELETE | Remove function |
/automation/v4/actions/callbacks/{callbackId}/complete | POST | Complete callback |
automation - Required for all action operationsA custom action definition includes:
{
"actionUrl": "https://your-service.com/webhook",
"objectTypes": ["CONTACT", "DEAL"],
"inputFields": [...],
"outputFields": [...],
"labels": {...},
"executionRules": [...],
"published": false
}
Configure what data workflow users can provide:
{
"typeDefinition": {
"name": "email_address",
"type": "string",
"fieldType": "text"
},
"isRequired": true,
"supportedValueTypes": ["STATIC_VALUE", "OBJECT_PROPERTY"]
}
Field Types:
| Type | Description | Use For |
|---|---|---|
string | Text | Emails, names, messages |
number | Numeric | Scores, amounts, counts |
bool | Boolean | Flags, toggles |
date | Date only | Due dates, birthdates |
datetime | Date + time | Scheduled times |
enumeration | Dropdown | Status, priority, type |
phone_number | Phone | Contact numbers |
object_coordinates | HubSpot record | Record references |
Supported Value Types:
| Type | Description |
|---|---|
STATIC_VALUE | User enters fixed value |
OBJECT_PROPERTY | Value from CRM property |
TOKEN | Dynamic token |
Define what data your action returns for workflow branching:
{
"typeDefinition": {
"name": "status",
"type": "enumeration",
"options": [
{ "value": "success", "label": "Success" },
{ "value": "failed", "label": "Failed" }
]
}
}
Serverless functions that run at specific points:
| Function Type | When It Runs | Purpose |
|---|---|---|
PRE_ACTION_EXECUTION | Before calling actionUrl | Modify request payload |
PRE_FETCH_OPTIONS | Before fetching external options | Customize option request |
POST_FETCH_OPTIONS | After fetching external options | Transform response |
PRE_ACTION_EXECUTION Example:
exports.main = async (event) => {
const { email, priority } = event.fields;
return {
email: email.toLowerCase(),
priority,
timestamp: new Date().toISOString(),
source: 'hubspot-workflow'
};
};
POST_FETCH_OPTIONS Example:
exports.main = async (event) => {
// Transform external API response to HubSpot format
return event.options.map(item => ({
label: item.name,
value: item.id,
description: item.description
}));
};
Custom error messages based on output:
{
"conditions": [
{
"propertyName": "status",
"operator": "EQ",
"value": "invalid_email"
}
],
"effect": {
"type": "ERROR",
"message": "The email address provided is invalid"
}
}
Multi-language support (14 languages):
{
"en": {
"actionName": "Enrich Contact",
"actionDescription": "Enriches contact with company data",
"actionCardContent": "Enriches {{inputFields.email}}",
"inputFieldLabels": {
"email": "Email Address",
"level": "Enrichment Level"
}
},
"es": {
"actionName": "Enriquecer Contacto",
"actionDescription": "Enriquece contacto con datos de empresa"
}
}
Supported Languages:
en, fr, de, es, pt-br, ja, nl, it, pl, fi, sv, zh-cn, zh-tw, ko
Your action URL receives POST requests:
{
"callbackId": "callback-abc123",
"origin": {
"portalId": 12345,
"actionDefinitionId": "def456"
},
"object": {
"objectType": "CONTACT",
"objectId": "789",
"properties": {
"email": "user@example.com",
"firstname": "John",
"lastname": "Doe"
}
},
"inputFields": {
"email_address": "user@example.com",
"priority": "high"
}
}
{
"outputFields": {
"status": "success",
"company_name": "Acme Corp",
"industry": "Technology"
}
}
{
"hs_execution_state": "BLOCK",
"hs_expiration_duration": "P1D"
}
Then complete later:
POST /automation/v4/actions/callbacks/{callbackId}/complete
{
"outputFields": {
"status": "success"
}
}
{
actionUrl: 'https://verify.example.com/email',
objectTypes: ['CONTACT'],
inputFields: [
{ name: 'email', type: 'string', required: true }
],
outputFields: [
{ name: 'valid', type: 'bool' },
{ name: 'deliverable', type: 'enumeration', options: ['yes', 'no', 'unknown'] },
{ name: 'risk_score', type: 'number' }
]
}
{
actionUrl: 'https://enrich.example.com/company',
objectTypes: ['CONTACT', 'COMPANY'],
inputFields: [
{ name: 'domain', type: 'string' },
{ name: 'enrichment_level', type: 'enumeration', options: ['basic', 'full', 'premium'] }
],
outputFields: [
{ name: 'company_name', type: 'string' },
{ name: 'employee_count', type: 'number' },
{ name: 'industry', type: 'string' },
{ name: 'revenue_range', type: 'string' }
]
}
{
actionUrl: 'https://notify.example.com/send',
objectTypes: ['DEAL', 'TICKET'],
inputFields: [
{ name: 'channel', type: 'string', required: true },
{ name: 'message', type: 'string', format: 'textarea' },
{ name: 'priority', type: 'enumeration', options: ['normal', 'urgent', 'critical'] }
],
outputFields: [
{ name: 'sent', type: 'bool' },
{ name: 'message_id', type: 'string' },
{ name: 'timestamp', type: 'datetime' }
]
}
{
actionUrl: 'https://lookup.example.com/data',
objectTypes: ['CONTACT'],
inputFields: [
{
name: 'data_source',
type: 'enumeration',
optionsUrl: 'https://lookup.example.com/sources',
optionsReferenceType: 'OPTION'
},
{ name: 'lookup_key', type: 'string', required: true }
],
outputFields: [
{ name: 'found', type: 'bool' },
{ name: 'result_data', type: 'string' }
]
}
skills/hubspot-workflow-patterns/ - Workflow automation patternsskills/hubspot-agent-standards/ - API patterns and rate limitsskills/hubspot-developer-platform/ - App development