Define serverless functions for project-built private apps

• UI extensions: using serverless functions for UI extensions requires an Enterprise subscription. You can also test out UI extensions for private apps for free in a developer test account.
• CMS: using serverless functions for CMS React projects requires a Content Hub Enterprise subscription.

• One or more JavaScript files that export a main function.
• A serverless.json file that registers and configures your functions. Learn more about serverless function configuration.

​

Create a serverless function

• App function: a serverless function that gets executed directly from within the project using the hubspot.serverless API.
• Endpoint function (Content Hub Enterprise only): an app function that is invoked by calling a public URL. The URL is determined by the account’s connected domains and the path specified in the serverless.json file. This is more common for implementing serverless functions for the CMS.

​

Configuration

{
  "appFunctions": {
    "functionName": {
       "file": "function1.js",
       "secrets": ["SOME_SECRET"],
       "endpoint": {
         "path": "path/to/endpoint",
         "method": ["GET"]
        }
     }
  }
}

​

Building the function

exports.main = async (context) => {
  return {
    statusCode: 200,
    body: { message: 'Hello World' },
  };
};

const axios = require('axios');

exports.main = async (context = {}) => {
  const { hs_object_id } = context.propertiesToSend;
  console.log(`Fetching inspirational quote for contact ${hs_object_id}`);

  try {
    const response = await axios.get('https://zenquotes.io/api/random');
    const quote = response.data[0];

    if (!quote) {
      throw new Error('No quote received from API');
    }

    console.log(`Retrieved quote: "${quote.q}" - ${quote.a}`);

    return {
      statusCode: 200,
      body: {
        quote: {
          text: quote.q,
          author: quote.a,
        },
      },
    };
  } catch (error) {
    console.error('ZenQuotes API request failed:', error.message);
  }
};

• CRM data components sample
• Duplicate a contact sample

​

Calling the function

import { hubspot, Button } from '@hubspot/ui-extensions';

hubspot.extend(() => <Extension />);

const Extension = () => {
  const handleSubmit = () => {
    hubspot
      .serverless('my-function-name', {
        propertiesToSend: ['hs_object_id'],
        parameters: { extra: 'data' },
      })
      .then((response) => {
        // handle response, which is the value returned from the function on success
      })
      .catch((error) => {
        // handle error, which is an Error object if the function failed to execute
      });
  };
  return <Button onClick={handleSubmit} label="Click me" />;
};

​

Endpoint functions

{
  "appFunctions": {
    "functionName": {
      "file": "somefunction.js",
      "secrets": [
        "SOME_SECRET"
      ],
      "endpoint": {
        "path": "path/to/endpoint",
        "method": [
          "GET"
        ]
      }
    }
  }
}

​

Authenticate requests

​

Private app access tokens

• Ensure the @hubspot/api-client library is included as a dependency in your project.
• In the serverless function JavaScript file, include @hubspot/api-client.
• Instantiate the client within exports.main and include PRIVATE_APP_ACCESS_TOKEN for authentication:

// Include HubSpot node API client
const hubspot = require('@hubspot/api-client');

exports.main = async (context = {}) => {
  // Get hs_object_id of the record in context
  const { hs_object_id } = context.propertiesToSend;
  console.log(`Looking up contact by ID [${hs_object_id}]`);

  // Instantiate HubSpot Node API client
  const hubspotClient = new hubspot.Client({
    accessToken: process.env['PRIVATE_APP_ACCESS_TOKEN'],
  });

  // Your function
};

• Configure the rest of the function using Node.js. For example, the following code would create a serverless function that retrieves the current contact by ID using the contacts API:

// Include HubSpot node API client
const hubspot = require('@hubspot/api-client');

exports.main = async (context = {}) => {
  // Get hs_object_id of the record in context
  const { hs_object_id } = context.propertiesToSend;
  console.log(`Looking up contact by ID [${hs_object_id}]`);

  // instantiate HubSpot Node API client
  const hubspotClient = new hubspot.Client({
    accessToken: process.env['PRIVATE_APP_ACCESS_TOKEN'],
  });
  const properties = ['firstname', 'lastname'];

  try {
    const apiResponse = await hubspotClient.crm.contacts.basicApi.getById(
      hs_object_id,
      properties
    );
    console.log(JSON.stringify(apiResponse));
  } catch (e) {
    e.message === 'HTTP request failed'
      ? console.error(JSON.stringify(e.response, null, 2))
      : console.error(e);
  }
};

• If you’re running HubSpot CLI version 7.0.0 or above, private app access tokens are automatically available for authentication as long as your personal access key has the developer.app_functions.write and developer.app_functions.read scopes.
• If you’re running HubSpot CLI version 6.x or below, you’ll need to add the token to a .env file within the .functions directory, as shown below. You can find the private app access token in the app’s settings in HubSpot.

PRIVATE_APP_ACCESS_TOKEN=pat-na1-******

​

Secrets

• Create a secret by running hs secrets add <secret-name>. HubSpot will securely store this secret on its backend and inject them into the runtime environment when a function is invoked in production.
• In the serverless.json file, include a secrets field within the corresponding function object, then specify the name of the secret. Do not include PRIVATE_APP_ACCESS_TOKEN in this array, as this is automatically created for you and already available in the serverless function.

{
  "appFunctions": {
    "functionName": {
      "file": "function1.js",
      "secrets": [
        "GITHUB_ACCESS_TOKEN"
      ]
    }
  }
}

• To make secrets available for local development, create a .env file in the .functions directory. HubSpot will never retrieve your secrets outside of its protected infrastructure, so you’ll need to specify the secret values that you want to use when the function is executed locally.

SECRET=my-secret-value
ANOTHER_SECRET=another-secret-value

• After saving secrets to the .env file, you can access them in your function using process.env['secretName'].

export const main = async (context) => {
  const secret = process.env['ANOTHER_SECRET'];
  const token = process.env['PRIVATE_APP_ACCESS_TOKEN'];
  ...
}

​

Managing secrets

• Create a secret by running hs secrets add <secret name>. HubSpot will securely store this secret on its backend and inject them into the runtime environment when a function is invoked in production.
• Update a secret by running the hs secrets update command. If you’re using a Node runtime of 14 or higher, updated secret values will automatically be updated in your deployed function within one minute, meaning you won’t have to build and deploy to get the updated secret.
• View existing secrets stored in your account by running hs secrets list.
• Delete a secret by running hs secrets delete <secret-name>. The command line will prompt you to confirm the deletion, which you can bypass by including the --force flag.

​

Best practices

​

Variable assignment inside functions

// Preferred
exports.myHandler = async (event, context) => {
  const myDynamicVariable = process.env['SOME_KEY'];
  // The rest of your handler logic
};

// Discouraged
const myDynamicVariable = process.env['SOME_KEY'];
exports.myHandler = async (event, context) => {
  // The rest of your handler logic
};

​

Stay up to date with the latest platform version

​

Including dependencies

{
  "name": "app.functions",
  "version": "1.0.0",
  "description": "",

  "dependencies": {
    "lodash": "^4.17.21"
  }
}

const _ = require('lodash');

exports.main = async (context) => {
  const objectA = {};
  const objectB = {};
  const equal = _.isEqual(objectA, objectB);
  return {
    statusCode: 200,
    body: {
      isEqual: equal,
    },
  };
};

​

Debug a serverless function

​

In-app debugging

• In your HubSpot account, navigate to CRM Development.
• In the left sidebar menu, navigate to Private apps.
• Select the private app that contains the serverless function.
• Click the Logs tab.
• To view logs for a serverless app function, click the Serverless functions tab. To view logs for a serverless endpoint function, click the Endpoint functions tab.
• In each tab, you can view logs for specific requests by clicking the request. You can also use the search bar to search by request ID.
• In the right panel, you can then click View log trace for a more in-depth breakdown of the request.

​

Local debugging

• Log messages that record the execution of a function, along with its status and timing. For example: 2021-04-28T19:19:21.666Z - SUCCESS - Execution Time: 279ms
• Log messages that are produced through console statements in the function code. For example, your serverless function JavaScript might include:

exports.main = async (context) => {
  console.log('Log some debug info');
  console.error('An error occurred');
  return {
    statusCode: 200,
    body: { message: 'Hello World' },
  };
};