How Do HubSpot Custom Code Actions Work?

HubSpot custom code actions let a workflow run your own JavaScript (Node.js) or Python code as a step, using data from the enrolled record. They are used to call external APIs, transform or validate data, and return output fields that later workflow steps can use. They require an eligible Operations Hub (Data Hub) Professional or Enterprise subscription.

Custom code actions sit between no-code workflows and a full custom integration. Used well, they remove the need for a separate middleware tool for many small jobs. Used badly, they create invisible, untested code in production. This guide covers both sides.

What can a custom code action do?

According to HubSpot's knowledge base article on custom code actions and the developer reference, a custom code action can:

• Read properties from the enrolled record that you pass in as input fields.
• Call HubSpot APIs using a private app access token stored as a secret.
• Call external APIs, for example an ERP, a billing system or an enrichment service.
• Return output fields that later actions can use in branches, property updates or emails.
• Run in supported runtimes: Node.js and Python (check HubSpot's docs for current versions and availability).

Typical uses include formatting phone numbers, calculating values across associated records, looking up a customer in an ERP, or round-robin logic that native rotation does not support.

When should you use custom code instead of native workflow actions?

Use native actions first. They are visible, auditable and maintained by HubSpot. Reach for custom code when:

1. You need an external API call that no native action or marketplace app provides.
2. The logic is conditional in ways branches cannot express cleanly, such as parsing text or complex date maths.
3. You need data from associated records combined in a way native actions cannot.
4. A small, focused task would otherwise require a separate integration platform subscription.

Avoid custom code when the job involves large data volumes, long-running processes or bidirectional sync. Those belong in a proper integration service; see our guide to ERP CRM integration.

How do you set up a custom code action step by step?

1. Create a private app in HubSpot settings with only the scopes your code needs, and copy its access token.
2. Open the workflow, add an action, and choose Custom code.
3. Add a secret for the token (and any external API keys). Secrets are referenced in code, not pasted into it.
4. Choose the runtime (Node.js or Python).
5. Define input properties from the enrolled record, for example email, company domain or deal amount.
6. Write the code, reading inputs from the event object and calling APIs as needed.
7. Define output fields with names and types, and return them from the function.
8. Test using the built-in test feature against a real record in a sandbox or test portal.
9. Use outputs in later steps: branches, property updates or notifications.
10. Turn on the workflow and monitor its history for errors.

What limits should you plan around?

HubSpot documents execution limits in its custom code actions reference. Check the current values before you design, but plan for:

• A short maximum execution time per run. Long API calls or loops will time out.
• Memory limits that rule out heavy processing.
• API rate limits, both HubSpot's and your external system's. A workflow that enrols thousands of records at once can hit them quickly.
• Retries. HubSpot can retry on certain errors, such as rate limiting. Your code must be safe to run more than once.
• Limited libraries. Only a set of packages is available in each runtime.

How do you make custom code reliable?

Treat every custom code action as production software:

• Make it idempotent. If the action runs twice, it should not create two invoices or two tasks. Use upserts and unique keys. Our article on CRM data hygiene and preventing duplicates explains the patterns.
• Validate inputs. Handle empty or malformed properties explicitly instead of letting the code throw.
• Handle errors deliberately. Catch failures from external APIs, return a clear status output, and branch on it.
• Keep secrets out of code. Always use HubSpot secrets, and rotate tokens when staff change.
• Use least-privilege scopes on the private app.
• Version your code outside HubSpot. Keep a copy in a Git repository with comments explaining each workflow it belongs to.
• Log meaningful messages. Console output appears in workflow history and is invaluable when debugging.

How do you test and debug custom code actions?

1. Use a sandbox or developer test account where possible.
2. Test with edge-case records: missing fields, unusual characters, multiple associations.
3. Read the workflow action logs for each enrolled record to see inputs, outputs and errors.
4. Simulate external failures by pointing to a test endpoint that returns errors.
5. Roll out gradually. Enrol a small segment first before turning a workflow on for all records.

What are common mistakes?

• Pasting tokens directly into code, which exposes them to anyone with workflow access.
• Building a sync engine inside a workflow, which is hard to monitor and replay.
• No documentation, so nobody knows why the action exists a year later.
• Ignoring enrolment volume, triggering rate limits during imports.
• Overly broad private app scopes.

Key takeaways

• Custom code actions run Node.js or Python inside HubSpot workflows and need an eligible Operations Hub (Data Hub) tier.
• Use them for focused tasks such as API lookups and data transformation, not full sync engines.
• Store tokens as secrets and give private apps the minimum scopes.
• Design for timeouts, rate limits and retries; make code idempotent.
• Version, document and test custom code like any other production system.

Frequently asked questions

Which HubSpot subscription do I need for custom code actions?

HubSpot lists custom code actions as part of Operations Hub, now marketed as Data Hub, at the Professional or Enterprise tier. Product packaging changes over time, so confirm the current requirement on HubSpot's pricing and knowledge base pages before planning.

Can custom code actions call external APIs?

Yes. You can make HTTP requests to external services, such as an ERP or billing system, and use the response as output fields. Store any API keys as HubSpot secrets and handle timeouts and error responses explicitly.

What languages do HubSpot custom code actions support?

HubSpot supports JavaScript on Node.js and Python. Supported runtime versions and available libraries change over time, so check the developer documentation for current details before writing new code.

What happens if a custom code action fails?

The failure is recorded in the workflow history for that record. HubSpot may retry certain errors, such as rate limits. Design your code to return a status output so later branches can handle failures, for example by creating a task for a human.

Should I use custom code or a dedicated integration?

Use custom code for small, event-driven tasks tied to a workflow. Use a dedicated integration service for bidirectional sync, high volumes, scheduled batch jobs or anything that needs replay and monitoring beyond workflow history.

Need help designing HubSpot automation?

Insyrge designs and builds HubSpot workflows, custom code actions and integrations that are documented and maintainable. Explore our HubSpot consulting service, our CRM API integration work, or get in touch.