Serverless functions reference

In the .functions folder, the serverless.json file stores the serverless function configuration. This is a required file, and maps your functions to their endpoints.

Each endpoint can have its own environment variables and secrets. Variables specified outside of endpoints should be used for configuration settings that apply to all functions and endpoints.

Endpoints have a couple unique keys.

Serverless functions are exposed through a path at your HubSpot CMS account’s domain. This includes default .hs-sites.com sub-domains.

You can access these functions at the following URL: 

https://{domainName}/_hcms/api/{endpoint-name/path}?portalid={hubId}.

Below, learn about each URL component:

In addition to the serverless.json configuration file, the .functions folder will also contain a Node.js JavaScript file that defines the function. You can also leverage the request library to make HTTP request to HubSpot APIs and other APIs.

For example:

The context object contains contextual information about the function's execution, stored in the following parameters.

If you need to know the headers of the client that's hitting your endpoint, you can access them through context.headers, similar to how you would access information through context.body.

Below, review some of the common headers that HubSpot provides. For a full list, see MDN's HTTP headers documentation.

You can perform a redirect from your serverless function by  sending a response with a location header and 301 statusCode.

From your serverless function you can tell the client (web browser) to set a cookie.

For headers that support multiple values, you can use multiValueHeaders, to pass the values. For example: you can tell the browser to set multiple cookies.

When you need to authenticate a serverless function request, you'll use secrets to store values such as API keys or private app access tokens. Using the CLI, you can add secrets to your HubSpot account to store those values, which you can later access through environment variables (process.env.secretName). Secrets are managed through the HubSpot CLI using the following commands:

• hs secrets list
• hs secrets add
• hs secrets delete

Once added through the CLI, secrets can be made available to functions by including a secrets array containing the name of the secret. This enables you to store your function code in version control and use secrets without exposing them. However, you should never return your secret's value through console logging or as a response, as this will expose the secret in logs or in front-end pages that call your serverless function.

When submitting serverless functions use javascript to handle the form submission, and use the "contentType" : "application/json" header in your request. Do not use the <form> elements action attribute.

Cross Origin Resource Sharing (CORS) is a browser security feature. By default browsers restrict cross-origin requests initiated by javascript. This prevents malicious code running on a different domain, from affecting your site. This is called the same-origin policy. Because sending and retrieving data from other servers is sometimes a necessity, the external server, can supply HTTP headers that communicate which origins are permitted to read the information from a browser.

You should not run into CORS issues calling your serverless function within your HubSpot hosted pages. If you do, verify you are using the correct protocol.

Get requests may be able to make CORS requests depending on the client. Do not make GET requests write anything, just return data.

HubSpot serverless functions currently come preloaded with the following packages:

• @hubspot/api-client: ^1.0.0-beta
• axios: ^0.19.2
• request: ^2.88.0
• requests: ^0.2.2

To use the latest supported version of a preloaded package, or to use a newly added package:

1. Clone or copy your function file.
2. Change your function's endpoint in the serverless.json file to point to your new function file. You can safely delete the old version.

If you want to include packages outside of the preloaded package set, you can use webpack to combine your node modules and have your bundled files be your function files.

Serverless functions are intended to be fast and have a narrow focus. To enable quick calls and responses, HubSpot serverless functions have the following limits:

• 50 secrets per account.
• 128MB of memory.
• No more than 100 endpoints per HubSpot account.
• You must use contentType application/json when calling a function.
• Serverless function logs are stored for 90 days.
• 6MB on an AWS Lambda invocation payload.

Execution limits

• Each function has a maximum of 10 seconds of execution time.
• Each account is limited to 600 total execution seconds per minute.

This means either of these scenarios can happen:

• 60 function executions that take 10 seconds each to complete.
• 6,000 function executions that take 100 milliseconds to complete.

Functions that exceed those limits will throw an error. Execution count and time limits will return a 429 response. The execution time of each function is included in the serverless function logs.

To assist in avoiding these limits, limit data is provided automatically to the function context during execution. You can use that to influence your application to stay within those limits. For example, if your application requires polling your endpoint, then you can return with your data a variable to influence the frequency of the polling. That way when traffic is high you can slow the rate of polling avoiding hitting limits, then ramp it back up when traffic is low.