static-auth v3 project card calling an external HTTPS endpoint

Develop, Build & Integrate HubSpot-built Apps
1

Questions:

  1. For a static-auth v3 project card calling an external HTTPS endpoint via hubspot.fetch, what is the exact allowed header set?
  2. Is there any known limitation or additional requirement for outbound proxy calls from static-auth cards that would explain the persistent 431 in the setup?

I’m just trying to POST a small JSON payload from the card to my backend and would appreciate guidance on the supported pattern for headers in this scenario (especially whether Authorization is actually allowed here, and under what conditions).

2

Hi @Sna919 :waving_hand:

Thank you for reaching out to the Community!

I’d like to invite some community members who are subject matter experts in project cards and hubspot.fetch to join this conversation. Hello there @seosiri @RubenBurdin @danmoyle Would you be able to share any insights on the allowed header set for static-auth v3 cards (especially Authorization) and what commonly triggers persistent 431 errors when calling an external HTTPS endpoint? Your expertise would be greatly appreciated.

Best,
Victor

3

Thank you for thinking of me @Victor_Becerra but I think @Sna919’s question is beyond my particular skillset :grin:

@Sna919 if I were in your shoes, I’d take to an AI engine and pore over the resources that come up. I’d also check with the HubSpot Developer Community. Maybe someone there has good insights to help.

4

Thanks so much for the reply, @danmoyle — I really appreciate you taking a moment to weigh in. Totally understand, and your suggestion to check the Developer Community is a great call. Always grateful for your willingness to jump into these threads and help guide folks in the right direction :blush: Best, Victor

5

1) Allowed headers in hubspot.fetch (static-auth v3 card)

Only these are allowed:

Content-Type

Accept

Anything else (including small headers) is rejected.

2) Reason for persistent 431 Request Header Fields Too Large

Authorization headers are NOT allowed

HubSpot runs static-auth cards behind a locked outbound proxy

Any non-allowlisted header causes the proxy to reject the request

Payload size is irrelevant

This is expected behavior, not a misconfiguration.

3) Is Authorization allowed?

No. Never.

Authorization headers are blocked in all static-auth v3 cards.

Allowed only in:

HubSpot serverless functions

OAuth / CRM extensions

Backend-to-backend calls

4) Supported way to POST JSON from a static-auth card

hubspot.fetch(url, {

method: “POST”,

headers: {

“Content-Type”: “application/json”,

“Accept”: “application/json”

},

body: JSON.stringify(payload)

});

Authentication must be in the body or handled server-side.

TL;DR

Headers allowed: Content-Type, Accept

Authorization: :cross_mark: not allowed

431: expected proxy rejection

Fix: public ingress or serverless proxy

6

Thank you @seosiri for the reply. I updated my static-auth v3 card to use:
hubspot.fetch(“<redacted-url>”, {
method: “POST”,
headers: {
“Content-Type”: “application/json”,
“Accept”: “application/json”,
},
body: JSON.stringify({
secret: “<redacted-secret>”,
data: { /* some small JSON payload */ }
}),
});

No Authorization or other custom headers; authentication is only in the body.
However, I’m still consistently seeing:
{
“message”: “Only ‘Authorization’ header is allowed. For questions about this, please use: HubSpot Developer Feedback Form”,
“category”: “REQUEST_HEADERS_FIELDS_TOO_LARGE”
}

Questions:

1. Is this expected when a static-auth v3 card POSTs to an external HTTPS domain via hubspot.fetch + /execution/internal/v3/proxy, even when only Content-Type and Accept are set and all auth is in the body?
2. If so, what is the recommended pattern for a static-auth v3 card that needs to send a small JSON payload to an external backend?

7

Step-by-step

1. UI Extension (static-auth v3 card)

Your card must NOT call external HTTPS services directly.

Instead, call a HubSpot serverless function:

hubspot.fetch(“/_hcms/api/my-proxy-endpoint”, { method: “POST”, headers: { “Content-Type”: “application/json” }, body: JSON.stringify({ data: { /* small JSON payload */ } }) });

:check_mark: Internal calls are allowed
:check_mark: No proxy header restrictions
:check_mark: Fully supported

8

Your serverless function then safely calls your external backend using fetch / axios:

exports.main = async (context, sendResponse) => {

const payload = context.body;

const response = await fetch(“https://external-domain.com”, {

method: “POST”,

headers: {

“Content-Type”: “application/json”,

“Authorization”: “Bearer YOUR_SECRET”

},

body: JSON.stringify(payload),

});

const result = await response.json();

sendResponse({ body: result });

};

:check_mark: Full control over headers
:check_mark: Auth can be in headers or body
:check_mark: No HubSpot proxy restrictions

9

Thank you @seosiri and @RubenBurdin

10

Hey @Sna919

Yeah this is a frustrating one. The error message is actually a bit misleading, it says “Only Authorization header is allowed” but thats not quite accurate for static-auth cards. What’s happening is the outbound proxy for static-auth v3 cards is extremely restrictive and basically blocks most external calls regardless of headers.

seosiri’s suggestion is the right path forward. You need to route through a HubSpot serverless function as an intermediary. The card calls your serverless function internally (which works fine), then the serverless function makes the actual external call with whatever headers you need. Its an extra hop but its the only reliable pattern I’ve seen work consistently.

One thing to double check, make sure your serverless function is defined in your project’s serverless.json and the endpoint path matches what you’re calling from the card. I’ve seen folks get tripped up when the function isn’t properly registered or the route doesnt match. HubSpot’s docs on serverless functions cover the setup (https://developers.hubspot.com/docs/platform/serverless-functions).

If the reason you need to call your backend is to sync or pull data into HubSpot records, there might be simpler approaches depending on your use case. At Stacksync we handle alot of HubSpot to database sync scenarios where people originally tried building custom integrations and ran into exactly these kinds of platform limitations. Sometimes the easier path is keeping the data in sync automatically rather than fetching on demand from a card. Note: This response was written based on my own experience and lightly reformatted with AI for clarity.

Hope you get it sorted!