GoHighLevel Custom Code Action in Workflows (2026)

By Dr Priya Jaganathan, GoHighLevel Certified Admin · HL Growth Partner, Australia · Updated 27 September 2026 · 10 min read

The GoHighLevel custom code action is the escape hatch every agency reaches for once If/Else branches and custom values stop being enough. It drops a genuine JavaScript step into the middle of a Workflow, so you can reshape a payload, normalise a phone number or run maths that the visual builder simply cannot express.

It is also, technically, a HighLevel custom JavaScript action running as a billed premium step — which changes how you should plan, test and price it before you point it at live contacts.

What the GoHighLevel custom code action actually does

HighLevel's own documentation describes it plainly: Custom Code lets you build logic "not available currently" inside the standard action library. In practice, it's a JavaScript sandbox sitting inside a single Workflow step.

You get a code editor, a test panel, and one job: take whatever comes in, transform it, and return an object the rest of the Workflow can use. It sits between your triggers and your later actions — SMS, email, tag, webhook, pipeline move — as a processing layer.

It is not a general-purpose server. There's no persistent state between runs, no scheduled jobs, and the documented use case is transformation and light computation, not hosting an application.

Where it fits against the rest of the action library

Think of it sitting alongside manual actions, If/Else branches and native integrations. Most Workflows never need it — you reach for Custom Code specifically when those tools run out of expressive power.

How data gets into a HighLevel custom JavaScript action

Everything the snippet can see arrives through mapped inputs. You define input variables in the action's setup panel, map them to contact fields, custom values, or the output of a prior step, and the code reads them off an inputData object — either inputData.phone or inputData['phone'].

• Contact fields — first name, phone, email, any custom field on the contact record.
• Custom values — account-level constants such as a booking link, a business name, or a rate card figure.
• Prior step output — the JSON a webhook step captured, or the object a previous Custom Code step returned.

Whatever you don't explicitly map, the snippet can't see. That's a deliberate constraint — it keeps the action from silently depending on data nobody documented.

Testing pulls real contact data, not custom values

HighLevel's support documentation is specific here: when you test the action, contact information passes through, but custom values do not. If your logic depends on a custom value, you'll need to test the downstream steps in context, not just the isolated code panel.

What the return value does downstream

The snippet must return a JavaScript Object (or an Array of Objects). That returned shape becomes a data source the rest of the Workflow can reference — you map its fields into later actions exactly like you'd map a contact field.

This is the entire point of the action. A well-formed return value turns messy input — a webhook blob, an unformatted phone number, a raw date string — into clean fields your SMS templates, tags and pipeline updates can actually use.

Realistic use cases agencies actually build

After building these for clients across trades, health and professional services, the same handful of jobs come up again and again.

Normalising Australian mobile numbers to E.164

Leads arrive as 0412 345 678, +61412345678, or 61 412 345 678 depending on the form that captured them. A short snippet strips spacing, checks the leading digits, and rewrites everything to the strict +61412345678 format that Twilio/LeadConnector SMS delivery expects — before a bad number causes a silent send failure.

Date maths and timezone handling

"Send a reminder 26 hours before the appointment, in the contact's local timezone" is a one-line sentence and a genuinely fiddly calculation once daylight saving is involved. Custom Code does the maths once and hands the Workflow a clean ISO timestamp to schedule against — this pairs naturally with a Wait step tuned to business hours.

Splitting, joining and parsing strings

Combining a first name, suburb and service type into one clean SMS line, or pulling a booking reference out of a longer string a form dumped into a single field — trivial in JavaScript, impossible in the native field mapper.

Parsing a webhook payload

Third-party tools rarely send data in the flat shape a Workflow wants. Custom Code sits right after an inbound webhook trigger and flattens nested JSON into the individual fields your later steps can map to — worth reading alongside a dedicated guide on inbound and outbound webhook setup before you build this pattern.

Building a signed URL

Some integrations require a URL with an HMAC signature or a time-limited token appended before a link is valid. That's a computation, not a lookup, and it belongs in code rather than a chain of text-replace custom values.

Conditional logic If/Else can't express

Multi-branch scoring — "if the lead is in NSW or VIC, has a budget field over a threshold, and hasn't been tagged 'lost' in the last 90 days" — is one if statement in JavaScript and an unreadable stack of nested If/Else branches in the visual builder.

Why it's a premium action — and what that means for the agency wallet

HighLevel classifies Custom Code as a Premium Action, billed per execution rather than bundled into your subscription. Every sub-account gets 100 complimentary premium executions, then usage draws down the agency wallet at the standard $0.01 rate, or a lower rate if that sub-account carries a paid Workflows Pro Plan tier.

Figures per HighLevel Support Portal, "Workflows Pro Plan Pricing," updated September 2025. Every run of a Custom Code step counts as one execution against this allowance, whether or not the run succeeds — so a snippet that errors and gets retried can still be metered.

The practical read: a Custom Code step that runs on every inbound lead across a busy sub-account is a running cost, not a one-off build fee. Model it against your full premium action cost breakdown before you promise a client "unlimited automation" at a flat price.

Neither the Custom Code support article nor its changelog entry states a specific execution timeout or memory ceiling. Treat it as built for short, synchronous transformations rather than heavy computation — HighLevel simply hasn't published a number to design against.

When Custom Code is the wrong tool

The most expensive mistake agencies make with this action isn't a bug in the code — it's reaching for it when a cheaper, more maintainable option was sitting right there.

If you already have an endpoint that does the job, a webhook to your own server is usually cheaper and easier to version-control than a growing snippet buried in a Workflow step. Custom Code wins when the logic is short and self-contained.

Operational discipline: treat every snippet like production code

A Custom Code step is still code running against live client data. It deserves the same discipline you'd apply anywhere else.

• Keep a version and a comment header. A one-line date and purpose comment at the top of the snippet saves the next person — often future-you — from guessing what it does.
• Never hardcode an API key in the snippet. Anyone with edit access to the Workflow can read the code panel; route secrets through your own backend instead.
• Log what you'll need to debug. A few console.log lines around the input and the return value make the test panel worth using when something breaks.
• Always handle the null or empty-field case. A missing phone number or blank custom value should return a safe default, not throw an unhandled error mid-Workflow.
• Test on a single contact before going live. Use the test panel, then run one real contact through the full Workflow before you let it touch your active list.

If something does go wrong once it's live, work through it the same way you'd debug any other step — see our Workflow troubleshooting guide for the order to check triggers, filters and action logs.

For the official field list and current editor behaviour, HighLevel's Custom Code support article and the Workflows Pro Plan pricing page are worth bookmarking — HighLevel updates both without much fanfare.

Common mistakes to avoid

• Shipping a snippet straight to a live Workflow without testing it against a single real contact first.
• Hardcoding an API key or webhook secret directly in the code panel.
• Assuming custom values are available during testing, when only contact fields are passed through.
• Building elaborate branching logic in Custom Code that a simple If/Else action would have handled for free.
• Ignoring the null/empty case, so one contact with a blank field halts the whole Workflow run.
• Never checking the wallet ledger, so premium execution charges from a high-volume Workflow go unnoticed for months.

If you want a second set of eyes on which of your Workflows should carry a Custom Code step versus a webhook or a custom value, book a strategy call with the HL Growth Partner team.

Book Your Strategy Call →

Frequently asked questions

What is the GoHighLevel custom code action used for?

It runs a JavaScript snippet inside a Workflow to transform data the visual builder can't handle — reformatting phone numbers, doing date maths, parsing webhook payloads, or building conditional logic more complex than If/Else can express.

Is the HighLevel custom JavaScript action free to use?

No. HighLevel classifies it as a Premium Action billed per execution. Each sub-account gets 100 complimentary executions, then it draws from the agency wallet at the standard rate or a lower rate under a paid Workflows Pro Plan tier.

What data can a Custom Code action see?

Only what you explicitly map into it — contact fields, custom values, and the output of earlier Workflow steps — accessed inside the snippet through an inputData object.

What must the Custom Code snippet return?

A JavaScript Object or an Array of Objects. That return value becomes available to later Workflow steps the same way a contact field or custom value is.

Does testing the action use real contact data?

Yes for contact fields, no for custom values. HighLevel's test panel passes through actual contact information but does not pass mapped custom values, so logic depending on a custom value needs an in-context test.

Is there a documented execution time limit?

HighLevel has not published a specific timeout or runtime limit in its support documentation. Treat the action as built for short, synchronous transformations rather than long-running processes.

When should I use a webhook instead of Custom Code?

When you already have your own endpoint, or the logic is complex enough to deserve proper version control and testing outside a Workflow step — a webhook to your own server is usually cheaper to maintain than a growing JavaScript snippet.

Can I put API keys in a Custom Code snippet?

You shouldn't. Anyone with edit access to the Workflow can read the code panel, so secrets belong behind your own backend, not hardcoded in the action.

Related Articles on HL Growth Partner

Workflow building blocks

• Setting Workflow goals and exit conditions
• Using manual actions inside Workflows
• Tracking clicks with trigger links

Data and integrations

• Modelling data with custom objects
• Connecting Google Sheets to your sub-account

Scaling the agency

• Building a tag naming strategy that scales
• Setting up and pricing an AI Employee