Custom Coded Actions (CWAs) in HubSpot workflows—now part of Data Hub (formerly Operations Hub)—unlock a new level of automation flexibility. With a few lines of code, you can execute complex processes that would otherwise require dozens of workflow actions. But while powerful, CWAs also come with trade-offs in complexity and maintainability.
This post covers best practices for building and managing CWAs so your workflows are efficient, scalable, and easy for your team to use.
Why use custom coded actions?
- Speed: A single CWA can replace 4x workflows and 50x workflow actions. Another benefit is speed: instead of waiting for HubSpot to process action after action, a CWA often completes the work much faster.
- Flexibility: Call external APIs, transform data, and handle conditions that aren’t possible with out-of-the-box workflow actions.
- Precision: Enforce business rules and handle edge cases that visual branching may not cover.
There are trade-offs. Despite AI being able to generate some code, CWAs are still code. They can be harder for non-technical users to manage than visual branching that routes deals based on type, for example.
Best practices
1) Implement robust error handling and logging
- Return an explicit error state when something breaks, rather than marking the action as success.
- Write concise, human-readable logs so non-technical teammates can triage.
- Branch the workflow on success vs. failure and notify internally on failure (include a link to the exact failed action log).
// Example pattern (Node.js runtime in CWA)
exports.main = async (event, callback) => {
try {
// ... your business logic
if (!event.inputFields.email) {
throw new Error("Missing email");
}
// Return values to workflow
callback({
outputFields: { status: "ok" }
});
} catch (err) {
console.log(`CWA ERROR: ${err.message}`);
callback({
isSuccess: false, // signal failure for branching
outputFields: { error: err.message }
});
}
};
2) Comment your code generously
Explain each section in plain English so the flow is understandable without deep technical knowledge.
// Validate email format; if invalid, return an error so the failure branch triggers
// Normalize phone numbers to E.164 format for downstream integrations
3) Use clear names and descriptions
- Action name example: Format phone number for Salesforce sync
- Action description example: Validates and standardizes phone number to E.164; outputs standardized_phone
4) Keep actions small and modular
- Prefer multiple focused CWAs over one monolith.
- Easier troubleshooting and better adherence to the 20-second execution limit per CWA.
- Compose steps in the workflow for clarity and reuse.
5) Centralize editable variables
Place configuration values at the top so non-developers can safely adjust behavior without digging into logic.
// Editable settings
const MAX_RETRIES = 3;
const TIMEOUT_MS = 8000;
const API_ENDPOINT = "https://api.example.com/data";
const DEFAULT_REGION = "NA";
6) Validate and sanitize inputs
- Check required fields before running business logic.
- Normalize strings, numbers, and dates to expected formats.
- Guard against null/undefined to avoid silent failures.
function requireField(input, key) {
const val = input[key];
if (val === undefined || val === null || String(val).trim() === "") {
throw new Error(`Missing required field: ${key}`);
}
return val;
}
7) Make outputs predictable
- Always return a consistent shape for outputFields.
- Document what each output field means and how downstream actions should use it.
callback({
outputFields: {
standardized_phone: e164,
route_bucket: route, // "enterprise", "smb", "partner"
status: "ok"
}
});
8) Rate limits, retries, and timeouts
- Respect third-party API rate limits.
- Use exponential backoff with a cap.
- Set reasonable timeouts so the action completes within platform limits.
async function withRetry(fn, maxRetries = MAX_RETRIES) {
let attempt = 0;
while (true) {
try { return await fn(); }
catch (e) {
if (++attempt > maxRetries) throw e;
await new Promise(r => setTimeout(r, 200 * Math.pow(2, attempt)));
}
}
}
9) Security and secrets
- Do not hardcode API keys; use HubSpot secrets where possible.
- Never log sensitive data.
- Validate outbound requests and sanitize inbound responses.
10) Versioning and reusability
- Adopt semantic versioning in action descriptions (e.g., v1.2.0).
- Extract common utilities into reusable snippets you can paste into new CWAs.
- Maintain a simple changelog in the action description or a central doc.
Example: replacing multi-branch routing with a single CWA
Without CWAs, a workflow might use multiple branches to check deal type, product category, and region—leading to 50+ actions. With a CWA, one coded action can evaluate properties and return a route_bucket value. Downstream, a thin visual branch routes based on that single output. The workflow runs faster and is easier to maintain.
// Example routing
function routeDeal({ type, productCategory, region }) {
if (type === "New Business" && productCategory === "Enterprise" && region !== "LATAM") {
return "enterprise";
}
if (type === "Renewal") return "success";
return "smb";
}
Trade-offs to consider
- Accessibility: Visual branching is simpler for non-technical users. CWAs may require developer involvement.
- Maintainability: More power can mean more complexity. Without documentation, CWAs become hard to manage.
- Training: Provide lightweight guidelines and examples so the team builds consistent, reliable coded actions.
A simple operating checklist
- Define scope: what the CWA must do, inputs, outputs, time budget.
- Scaffold the action with comments, top-level settings, and predictable outputs.
- Add input validation, error handling, and logging.
- Test with representative records and failure cases.
- Document name, description, version, inputs, outputs, and known limitations.
- Monitor logs and iterate.
Bottom line
Custom Coded Actions in HubSpot’s Data Hub can act like jet fuel for automation. Use them to speed up heavy workflows, collapse complex logic, and integrate external services—while keeping things approachable through modular design, clear comments, robust error handling, and predictable inputs/outputs. That balance is what turns powerful code into reliable operations.
