Serverless Functions

Last updated:
APPLICABLE PRODUCTS
  • CMS Hub
    • Enterprise

Serverless functions provide a way to write server-side code that interacts with HubSpot and third-party services through APIs. APIs requiring authentication are not safe for the front-end of a website, as your credentials would be exposed. Serverless functions can act as an intermediary, enabling you to keep credentials secret. 

With serverless functions, developers don’t need to spin up and manage new servers. Serverless functions require less overhead and as a result they are easier to scale as a business grows.

The list of things you can use HubSpot serverless functions for is up to your imagination. You could use them for:

  • Collecting data and storing it in HubDB or the HubSpot CRM
  • Complex data calculators
  • Dynamically displaying data from other systems
  • Event registration systems
  • Form submissions that send data to other systems

Developers can experiment with serverless functions using their CMS developer sandbox account. API developer accounts and their test accounts can't currently use serverless functions, use a CMS Developer Sandbox account instead.

When you feel you are ready to begin building your first serverless function, see getting started with serverless functions.

What might this look like in practice?

Taking our event registration system example. Let's break down how you could use serverless functions to handle registration and update how many open slots there are for an event.

  1. The website visitor navigates to your event registration page, showing there is room for 15 more people to attend. The visitor fills out a custom form to sign up for the event, and submits.
  2. That submission we've set to send a POST request to yourwebsite.com/_hcms/api/event/participants. event/participants is your serverless function.
  3. Your serverless function receives the user submitted data and takes a few actions before returning a response to the browser:
    1. Submits the form field data to the HubSpot submit form API to add this form submission information to the HubSpot CRM.
    2. Uses the HubDB api, to subtract 1 from the participant count for this event which is stored in HubDB.
    3. Sends a response back to the web browser.
  4. Javascript in the page receives the response from the serverless function and displays a confirmation message to the end-user, and adjusting the count of how many slots are left for participants.

HubSpot’s serverless functions are written in JavaScript and use the NodeJS runtime.  HubSpot's serverless functions are intended to be used to add functionality to your HubSpot site, such as supporting advanced form submissions and pulling in data from other APIs. It’s not intended as a generic computing platform where you would run code unrelated to HubSpot.

Know your limits

Serverless functions are intended to be fast and have a narrow focus. That speed enables them to be perfect companions to the front-end of websites and apps, enabling a quick call and response. HubSpot serverless functions are limited to:

  • 50 secrets per account
  • 128MB of memory
  • 10 seconds of execution time
  • 60 function executions per minute
  • 600 seconds (10 minutes) of function execution time per minute. This means that in a single minute, 60 functions that complete in 10 seconds could run OR 600 function executions that complete in 1 second could run.
  • No more than 100 endpoints per HubSpot account

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.

Serverless function files live in the developer file system

The code for these functions is stored in the developer file system, visible in the Design Manager UI and accessible through the CLI. These functions are editable locally using the local development tools to upload/download. This is ideal for using with build processes and version control.

Serverless function folders

HubSpot Serverless functions live inside a functions folder. This folder can be named anything, but must contain the suffix .functions. This is similar to what you see with modules when using the local development tools to edit. They are "module label.module". 

Within the functions folder you will include your .js files which will contain your functions, and your serverless.json file. You might consider adding a README markdown file to communicate what the functions are for, how they work, and if you have a build process to author them.

Files stored in this folder are not publicly accessible.

Serverless .functions folder

To prevent accidental edits from within the Design Manager, lock the folder to indicate your files should not be edited in Design Manager. Right click the folder in the design manager and choose"Lock folder".

Serverless.json

serverless.json acts as your config file for your serverless functions, you specify the runtime environment, and any environment variables you plan to use in your functions there.

This file also handles the routing of your endpoints. You specify the endpoint paths you want to map to your function.js files. For an example of what your serverless.json file should look like see our reference.

Function.js

Your actual serverless function can be named anything as long as it is a js file.  For your serverless function to do anything at all it must be mapped to an endpoint defined in the serverless.json file. A good recommendation is to name the js file similarly to your endpoint name in your serverless.json configuration file. That can help with troubleshooting.

Secrets

API keys, and authentication information are referred to as secrets. Secrets are added and removed through the HubSpot CLI. Once added through the CLI, they can be made available to specific functions or globally, by adding a secrets array, with the name of the secret. Once added they are accessible within functions through environment. This provides you a secure way to use these secrets and enable you to store your function code in version control, without worrying about the secrets being exposed.

Do not return your secret's value through console logging or as a response. Doing so would expose your secrets in your logs or in front-end pages that call your serverless function.

Viewing serverless function logs

To help with troubleshooting your serverless functions, the CLI has an hs logs command which gives you the ability to view your function’s logs. In addition to individual function invocation responses, time of execution, and execution time, any console.log statement will also appear in function logs. Do not console.log secrets like API keys.