How to save settings from UI Extension? Keep getting errors [HubSpot Platform 2025.2]

[tombonneau]

Howdy Community of Developers Waaaaaay Smarter Than Me,

So full disclosure, I am a product dev/marketer with very limited JS experience using Claude Code (who also helped put together some of this post of course!) to help me jump start an MVP HS app that will integrate with our own product (CRM communication platform).

I've made some good progress as far as syncing contacts and events back and forth between the systems, including a custom workflow action to push contacts into 3rd party CRM.

But I am now at a bit of a road block. I'm hoping there is just some fundamental HS 25.2 setting I am overlooking/not understanding as a non-dev person that a seasoned pro can point out rather quickly. 😃

Basically, I'm building a UI Extension for HubSpot Platform 2025.2 and struggling to save settings from a Settings Page component. I am able to get the UI to show the HS field options for sync, our other CRM field options to sync, but when I try to save I get constant errors. This console screenshot is pretty standard set of errors:

What I'm Trying to Do

I have a Settings Page (`settingsPage.json`) where users can configure field mappings between HubSpot contact properties and our external CRM. I need to:

1. Load HubSpot contact properties (this works ✅)

2. Save the user's field mapping configuration (this fails ❌)

The Problem

According to the HubSpot Platform 2025.2 Settings documentation, it says:

> "Use hubspot.fetch to leverage your backend to save and retrieve settings."

However:

- `hubspot.fetch()` only supports GET requests to external HTTPS URLs

- I need to POST data to save settings

- Serverless functions cannot make outbound HTTP requests (confirmed - they never reach my webhook server)

What I've Tried

Attempt 1: Save via Serverless Function ❌

```javascript

// In Settings Page

const response = await runServerlessFunction({

name: "save-field-mappings",

parameters: { fieldMappings: mappings },

});



// In serverless function

const response = await fetch(WEBHOOK_URL, {

method: 'POST',

body: JSON.stringify({ fieldMappings })

});

Result: 500 error. The fetch() call never reaches my webhook server (confirmed via logs).

Attempt 2: Direct hubspot.fetch() with GET ❌

// Encode data as URL parameter since hubspot.fetch() only supports GET

const encoded = encodeURIComponent(JSON.stringify(mappings));

const response = await hubspot.fetch(

`${WEBHOOK_URL}/api/settings/save?data=${encoded}`,

{ method: "GET" }

);

Result: This causes the entire Settings Page to fail loading with "Failed to load settings: API error: 500"

Attempt 3: hubspot.api.appSettings ❌

I also tried using hubspot.api.appSettings.set() but this API doesn't exist in serverless functions.

Questions

1. What is the correct way to save settings in HubSpot Platform 2025.2?
   • The docs say "use hubspot.fetch to leverage your backend" but it only supports GET
   • Should I be using a different API?
2. Can serverless functions make outbound HTTP requests?
   • My testing suggests they cannot (requests never reach my server)
   • Is this a platform limitation?
3. Is there a built-in settings storage API I'm missing?
   • Something like a key-value store for app settings?

My Setup

• Platform Version: 2025.2
• Project Structure:
• src/
• app/
• settings/
• SettingsPage.tsx
• settings.functions/
• save-field-mappings.js
• get-hubspot-properties.js
• Backend: Express.js webhook server (via ngrok for dev)
• Auth: Private app with crm.objects.contacts.read scope

Code Files

SettingsPage.tsx (relevant excerpt):

const saveFieldMappings = async (mappings: FieldMapping[]): Promise<void> => {

const encodedMappings = encodeURIComponent(JSON.stringify(mappings));

const response = await hubspot.fetch(

`${WEBHOOK_SERVER_URL}/api/settings/field-mappings/save?data=${encodedMappings}`,

{ method: "GET" }

);



if (!response.ok) {

throw new Error(`API error: ${response.status}`);

}



const data = await response.json();

if (!data.success) {

throw new Error(data.error || "Failed to save field mappings");

}

};

save-field-mappings.js (serverless function):

exports.main = async (context) => {

try {

const { fieldMappings } = context.parameters;



// This never reaches the webhook server

const response = await fetch(WEBHOOK_URL, {

method: 'POST',

headers: { 'Content-Type': 'application/json' },

body: JSON.stringify({ fieldMappings }),

});



if (!response.ok) {

throw new Error(`Webhook error: ${response.status}`);

}



return { success: true };

} catch (error) {

return { success: false, error: error.message };

}

};

 

Expected Behavior

Settings should save successfully to my backend server, similar to how loading HubSpot properties works (that uses hubspot.fetch() with GET and works fine).

Actual Behavior

• Attempt 1: 500 error, request never reaches webhook server
• Attempt 2: "Failed to load settings: API error: 500" on page load

Any guidance would be greatly appreciated! Is there official example code for saving settings in Platform 2025.2?

Thanks!

Tom