Skip to main content

Supported products

Requires one of the following products or higher.

  • Content 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 between your front-end and back-end services that require authentication. 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. We have a high level overview of what HubSpot serverless functions are and how they work, we recommend reading through before doing this tutorial.

This tutorial will guide you through the creation of your first serverless function.

You will create a serverless function folder, set up your configuration folder, create a function and get a response from it.

What you should do before taking this tutorial:

Open your hubspot.config.yml file, and make sure your defaultPortal is set to either your CMS Developer Sandbox account or an account with CMS Hub Enterprise.

On your computer, in the folder that contains your hubspot.config.yml file, create a serverless-tutorial folder. This folder will contain all of our files, both the functions themselves and a template which will use the function.

In your terminal run the watch command:

This will cause any edits to this folder to result in uploads to the design manager. Since the folder currently has no content, this command will simply state Watcher is ready and watching.

Inside of the serverless-tutorial folder create a my-first-function.functions folder. This is similar to custom modules folders which end in .module, .functions serves to communicate that folder contains serverless functions. Files stored in this folder are not publicly accessible.

Because this folder is currently empty the watch command you have running will not create this folder in the Design Manager yet.

Create a new file in your my-first-function.functions folder, name it serverless.json. serverless.json is a required file contained within a .functions folder. It serves as a configuration file for serverless functions. Defining the runtime environment, serverless function version, and available endpoints. For a rundown of everything that gets defined in this file, see our serverless reference.

Paste the code below into your serverless.json:

Save the file.

Keep this file open in your code editor, we will be coming back to it.

Because watch is running, if you refresh your design manager you will now see your serverless-tutorial and my-first-function.functions folders and your new serverless.json file.

Create a new file in your my-first-function.functions folder, name it congratulation.js

This is the actual function file, the file that will execute and perform a task.

Paste in the code below:

This serverless function when executed returns a string "Congrats! You just deployed a Serverless Function." and a status code of 200, indicating success.

You are not done yet, there is no way to execute this function just yet.

Open your serverless.json file again. In your file find your "endpoints" object.

Update the object to look like this:

The endpoints object contains a "congratulation" object. "congratulation" is the endpoint you're creating. The endpoint's name is what defines the path that you will use to call your serverless function.

Serverless functions are exposed through a path at your HubSpot CMS account’s domain.

These functions can be accessed at:

<https://www.example.com>/_hcms/api/<endpoint-name/path>

In the case of this "congratulation" endpoint you've created, it will be

<https://www.example.com>/_hcms/api/congratulation

Because of this it is generally a good idea to name your endpoint similarly to your function file's name, and both should be named based on the information they act against, not the action taken against that information. You should use the HTTP method or methods for communicating the type of action you are making against that information. The "method" parameter defines the HTTP method's your function supports. It can be a single string or an array of strings denoting the methods the function supports.

The simplest way to test a GET request to your serverless function is to go to your endpoint's URL directly in the browser. https://your-domain.com/_hcms/api/congratulation

Replacing your-domain.com with your HubSpot site's domain.

You should see "Congrats! You just deployed a serverless function".

Success, you did it!

If you do not get that response, start from the top of this tutorial carefully reading each step and verifying the code. It is likely instructions in step 4 or 5 were not followed correctly.

Using a new terminal window navigate into your serverless-tutorial folder using cd.

Run the following command in your terminal:

This creates a test-function.html file. Open this file in your code editor.

Above the </head> tag add <script></script>.

Copy the javascript below:

Inside of the script tag you created earlier, paste your copied JavaScript code.

Change www.example.com to your account's domain.

Save the file.

In the design manager find your test-function.html file (you may need to refresh)

Right click the file, choose "create page".

Name your page "Test Function". Create page.

Click preview, preview in new window.

Inspect the page by right clicking anywhere on the page and selecting "inspect".

If you did everything correctly you should see in your console the congratulations message.

Congratulations, you've called your serverless function from within a HubSpot CMS page.

At this stage your serverless function should work fine. The more complicated your function gets, the harder it is to troubleshoot. Just like the console in your browser is useful for debugging javascript on your front-end, you can get similar logs for your serverless functions using hs logs. Check out the local development reference for more information on this command.

You created a serverless function folder, with a serverless.json configuration file, and function file named congratulation.js. You used "GET" to get congratulations text from the serverless function. You used javascript to make a call to your serverless function from a page on the HubSpot CMS.

Now that you understand how the configuration file, function file, and .functions folder relate, the CLI has a handy command you can use to create your functions faster next time.

This function creates a .functions folder, serverless.json file and a function file with the names you provide.