Update optionsUrl for custom workflow action

[SSun7]

Hi, I've created a custom workflow action for my public app, but now I want to update the optionsUrl field in the first object in inputFields. Here's my steps:
1. get the current workflow action definition via GET request to

automation/v4/actions/${APP_ID}/${ACTION_ID} with developer API key;

2. update the url: action.inputFields[0].typeDefinition.optionsUrl = newUrl;

3. update the workflow action via PATCH request to automation/v4/actions/${APP_ID}/${ACTION_ID} with developer API key.
However, I keep receiving 'Invalid action definition' error.

[RubenBurdin · Accepted solution]

Hi @SSun7 , that “Invalid action definition” usually happens because the payload you PATCH is not a valid definition body, even if you started from a GET.

The PATCH endpoint accepts a specific schema and will reject read-only fields or shapes that don’t match the definition contract. In practice, if you take the full GET response (with things like id, revisionId, functions, timestamps, etc.) and send it back, HubSpot can throw that generic validation error.

The safest pattern is to build a clean PATCH body that includes only the fields the endpoint documents as writable (for example actionUrl, inputFields, published, etc.), and make sure your inputFields[].typeDefinition is still fully valid. For optionsUrl specifically, HubSpot expects it to be used with external options fields, meaning typeDefinition.externalOptions should be true and the field type must be one that supports options, not a plain text input. If your first input is fieldType: text, adding optionsUrl will fail validation. The contract for the update endpoint is here (https://developers.hubspot.com/docs/api-reference/automation-actions-v4-v4/definitions/patch-automat... )

One quick clarifying question: did you create this action via a Developer Project (new platform) and deploy it with hs project upload, or did you register it purely via the Actions API? If it’s project-based, the “source of truth” is your workflow-action-hsmeta.json, and updates should be done by changing that file and re-deploying, not patching via the definitions endpoint (https://developers.hubspot.com/docs/apps/developer-platform/add-features/custom-workflow-actions ) If you share the exact PATCH JSON you’re sending (redacting secrets), it’s usually easy to spot the one field or missing piece that triggers the validation.

[SealaB]

Hi there, @SSun7 - 

Tagging in a few of our API and custom workflow actions experts here - I'll check back in to ensure you're getting a response. 
Hey @ChristinaKay, @ChrisoKlepke, and @HubSpot_Corey - any thoughts on this?

[SSun7]

Hi, is there any update here? I really need a clear answer on this as quickly as possible.

[SealaB]

Thanks for contributing to the discussion, @RubenBurdin - let us know if you have further questions on Ruben's response, @SSun7!