Productos compatibles
Se requiere uno de los siguientes productos o productos de ediciones superiores.
Content HubContent HubEnterprise
Última modificación: 28 de agosto de 2025

Nota:

Esta página contiene información de referencia para las funciones sin servidor creadas con el administrador de diseño. Históricamente, esta es la forma original de crear funciones sin servidor para tus páginas CMS y todavía es admitido. Sin embargo, en el futuro se recomienda crear y desplegar funciones sin servidor con los proyectos para desarrolladores de HubSpot. Las funciones sin servidor basadas en proyectos pueden incluir dependencias de terceros y tener un acceso más directo a la autenticación mediante tokens de acceso a aplicaciones privadas.
En este artículo, aprende sobre los archivos que se encuentran dentro de una carpeta .functions sin servidor y los comandos CLI que puedes utilizar con las funciones sin servidor. Para obtener un resumen general de las funciones sin servidor, consulta la descripción general de las funciones sin servidor. Para obtener más información sobre la creación de funciones sin servidor con proyectos para módulos renderizados y parciales de JavaScript, consulta la documentación de proyectos de desarrollador.

Serverless.json

En la carpeta .functions, el archivo serverless.json almacena la configuración de la función sin servidor. Este es un archivo obligatorio y asigna tus funciones a sus endpoints.
{
  "runtime": "nodejs20.x",
  "version": "1.0",
  "environment": {
    "globalConfigKey": "some-value"
  },
  "secrets": ["secretName"],
  "endpoints": {
    "events": {
      "file": "function1.js",
      "method": "GET"
    },
    "events/update": {
      "method": "POST",
      "file": "action2.js",
      "environment": {
        "CONFIG_KEY": "some-other-value"
      },
      "secrets": ["googleKeyName", "otherkeyname"]
    }
  }
}
claveTipoDescripción
runtimeCadenaEl entorno de tiempo de ejecución. Compatible con Node.js v20 (nodejs20.x).
versionCadenaversión del esquema de funciones sin servidor de HubSpot. (Versión actual 1.0)
environmentObjetoVariables de configuración pasadas a la función ejecutante como variables de entorno en tiempo de ejecución. Puedes usar esto para agregar una lógica para usar una versión de prueba de una API en lugar de la real basada en una variable de entorno.
secretsMatrizUna matriz que contiene los nombres de los secretos que tu función sin servidor utilizará para la autenticación. No almacenes secretos directamente en este archivo, solo haz referencia a los nombres de los secretos.
endpointsObjetoLos endpoints definen las rutas que se exponen y tu asignación a archivos JavaScript específicos, dentro de tu carpeta de funciones. Obtén más información sobre los endpoints.
HubSpot dejará de dar soporte a Node 18 después del 1 de octubre de 2025. Después de esa fecha, las funciones sin servidor con un tiempo de ejecución inferior a la v20 no podrán desplegarse.

Nota:

No asignes el mismo nombre a tus secretos y variables de entorno. Si lo haces, se producirán conflictos al devolver tus valores en la función.

Endpoints

Cada endpoint puede tener sus propias variables de entorno y secretos. Las variables especificadas fuera de los endpoints deben utilizarse para los ajustes de configuración que se aplican a todas las funciones y endpoints.
"events/update": {
      "method": "POST",
      "file": "action2.js",
      "environment": {
        "configKey": "some-other-value"
      },
      "secrets": ["googleAPIKeyName","otherKeyName"]
    }
claveTipoDescripción
methodCadena o matriz de cadenasMétodo o métodos HTTP que admite el endpoint. El valor predeterminado es GET.
fileCadenaRuta al archivo de la función JavaScript con la implementación para el endpoint.
El endpoint puede invocarse llamando a una URL en uno de los dominios conectados a la cuenta de HubSpot, incluidos los subdominios predeterminados .hs-sites.com, con la siguiente estructura de URL: https://{domainName}/_hcms/api/{endpoint-name/path}?portalid={hubId}.
ParámetroDescripción
domainNameUn dominio conectado a la cuenta de HubSpot.
/_hcms/api/La ruta reservada para las funciones sin servidor. Todos los endpoints existen dentro de esta ruta.
endpoint-name/pathEl nombre del endpoint o la ruta que especificaste en el archivo serverless.json.
portalidUn parámetro de consulta opcional que contiene el ID de tu cuenta de HubSpot. Proporcionar esto en la solicitud te permitirá probar tus funciones dentro de las vistas previas de módulos y plantillas.
Por ejemplo, si website.com y subdomain.brand.com están conectados a la cuenta, podrías llamar a la función utilizando https://website.com/_hcms/api/{endpoint-name/path} o https://subdomain.brand.com/_hcms/api/{endpoint-name/path}.

Archivo de funciones

Además del archivo de configuración serverless.json, la carpeta .functions también contendrá un archivo JavaScript Node.js que define la función. También puedes aprovechar la biblioteca de solicitudes para realizar solicitudes HTTP a las API de HubSpot y otras API. Por ejemplo:
// Require axios library, to make API requests.
const axios = require('axios');
// Environment variables from your serverless.json
// process.env.globalConfigKey

exports.main = (context, sendResponse) => {
  // your code called when the function is executed

  // context.params
  // context.body
  // context.accountId
  // context.limits

  // secrets created using the CLI are available in the environment variables.
  // process.env.secretName

  //sendResponse is what you will send back to services hitting your serverless function.
  sendResponse({ body: { message: 'my response' }, statusCode: 200 });
};

Objeto de contexto

El objeto de contexto contiene información contextual sobre la ejecución de la función, almacenada en los siguientes parámetros.
ParámetroDescripción
accountIdEl ID de la cuenta de HubSpot que contiene la función.
bodyLleno si la solicitud se envía como POST con un tipo de contenido application/json.
contactSi la solicitud proviene de un contacto con cookies, el objeto contacto estará lleno con un conjunto de propiedades básicas junto con la siguiente información:
  • vid: ID de visitante del contacto.
  • isLoggedIn: cuando se utiliza CMS Memberships, esto será true si el contacto ha iniciado sesión en el dominio.
  • listMemberships: una matriz de ID de listas de contactos de las que este contacto es miembro.
headersContiene los títulos enviados por el cliente que llega a tu endpoint.
paramsRellenado con valores de cadena de consulta junto con cualquier valor HTML Form-POSTed. Se estructuran como un mapa con cadenas como claves y una matriz de cadenas para cada valor.context.params.yourvalue
limitsDevuelve lo cerca que estás de alcanzar los límites de velocidad de las funciones sin servidor.
  • executionsRemaining: cuántas ejecuciones por minuto quedan.
  • timeRemaining: cuánto tiempo de ejecución permitido queda.

Encabezados

Si necesitas conocer los encabezados del cliente que está llegando a tu endpoint, puedes acceder a ellos a través de context.headers, similar a cómo accederías a la información a través de context.body. A continuación, revisa algunos de los encabezados comunes que proporciona HubSpot. Para obtener una lista completa, consulta la documentación de encabezados HTTP de MDN.
títuloDescripción
acceptComunica qué tipos de contenido, expresados como tipos MIME, entiende el cliente. Consulta MDN.
accept-encodingComunica la codificación del contenido que el cliente entiende. Consulta MDN.
accept-languageComunica qué idioma humano y localización se prefiere. Consulta MDN.
cache-controlContiene directivas para el almacenamiento en caché. Consulta MDN.
connectionComunica si la conexión de red permanece abierta. Consulta MDN.
cookieContiene las cookies enviadas por el cliente. Consulta MDN.
hostComunica el nombre de dominio y el número de puerto TCP de un servidor de escucha. Consulta MDN.
true-client-ipDirección IP del usuario final. Consulta Cloudflare true-client-ip.
upgrade-insecure-requestsComunica la preferencia del cliente por una respuesta cifrada y autentificada. Consulta MDN.
user-agentCadena definida por el proveedor que identifica la aplicación, el sistema operativo, el proveedor de la aplicación y la versión. Consulta MDN.
x-forwarded-forIdentifica la dirección IP de origen de un cliente a través de un proxy o equilibrador de carga. Consulta MDN.

Redireccionamiento enviando un encabezado

Puedes realizar un redireccionamiento desde tu función sin servidor enviando una respuesta con un encabezado location y un statusCode 301.
sendResponse({
  statusCode: 301,
  headers: {
    Location: 'https://www.example.com',
  },
});

Establecer las cookies desde tu endpoint

Desde tu función sin servidor puedes decirle al cliente (navegador web) que establezca una cookie.
exports.main = (context, sendResponse) => {
    sendResponse({
      body: { ... },
      'Set-Cookie': 'myCookie1=12345; expires=...; Max-Age=...',
      statusCode: 200
    });
  }

Establecer varios valores para un solo encabezado

En el caso de los encabezados que admiten múltiples valores, puedes utilizar multiValueHeaders, para pasar los valores. Por ejemplo: puedes decirle al navegador que establezca varias cookies.
exports.main = (context, sendResponse) => {
  sendResponse({
    body: { ... },
    multiValueHeaders: {
      'Set-Cookie': [
        'myCookie1=12345; expires=...; Max-Age=...',
        'myCookie2=56789; expires=...; Max-Age=...'
       ]
    },
    statusCode: 200
  });
}

Secretos

Cuando necesites autenticar una solicitud de función sin servidor, usarás secretos para almacenar valores como claves de API o tokens de acceso a aplicaciones privadas. Con la CLI, puedes agregar secretos a tu cuenta de HubSpot para almacenar esos valores, a los que luego podrás acceder a través de variables de entorno (process.env.secretName). Los secretos se gestionan a través de la CLI de HubSpot utilizando los siguientes comandos: Una vez agregados a través de la CLI, los secretos pueden ponerse a disposición de las funciones mediante la inclusión de una matriz de secrets que contenga el nombre del secreto. Esto le permite almacenar tu código de función en el control de versiones y usar secretos sin exponerlos. Sin embargo, nunca debes devolver el valor de tu secreto a través del registro de la consola o como respuesta, ya que esto expondrá el secreto en los registros o en las páginas del front-end que llaman a tu función sin servidor.

Nota:

Debido al almacenamiento en caché, puede tardar aproximadamente un minuto ver los valores actualizados de los secretos. Si acabas de actualizar un secreto pero todavía estás viendo el valor anterior, vuelve a comprobarlo después de aproximadamente un minuto.

Uso de funciones sin servidor con el elemento de formulario

Al enviar funciones sin servidor, utiliza javascript para manejar el envío del formulario y utiliza el encabezado "contentType" : "application/json" en tu solicitud. No utilices el atributo <form> de los elementos action.

CORS

Intercambio de recursos de origen cruzado (CORS) es una función de seguridad del navegador. Por opción predeterminada, los navegadores restringen las solicitudes de origen cruzado iniciadas por javascript. Esto evita que el código malicioso que se ejecuta en un dominio diferente, afecte a tu sitio. Esto se denomina política del mismo origen. Dado que el envío y la recuperación de datos de otros servidores es a veces una necesidad, el servidor externo, puede suministrar encabezados HTTP que comunican qué orígenes están autorizados a leer la información de un navegador. No deberías tener problemas de CORS al llamar a tu función sin servidor dentro de tus páginas alojadas en HubSpot. Si lo haces, verifica que estás utilizando el protocolo correcto.
¿Recibes este error CORS? “Se ha bloqueado el acceso para obtener la [URL de la función] desde el origen [página que realiza la solicitud] debido a la política de CORS: la respuesta a la solicitud previa no supera la verificación de control de acceso; no se encontró el encabezado ‘Access-Control-Allow-Origin’ en el recurso solicitado. Si una respuesta opaca sirve a tus necesidades, establece el modo de la solicitud como ‘no-cors’ para obtener el recurso con CORS desactivado”¿Tu solicitud se dirige a un origen diferente al del sitio que la llama?
  • Si el nombre de dominio es diferente, sí.
  • Si utilizas un protocolo diferente (http, https), sí.
Si utilizas un protocolo diferente, simplemente cambia el protocolo para que coincida y eso lo arreglará.En este momento no se puede modificar el encabezado Access-Control-Allow-Origin de HubSpot.Consulta el MDN para obtener más detalles sobre la solución de errores de CORS.

Solicitudes Get

Las solicitudes Get pueden hacer solicitudes CORS dependiendo del cliente. No hagas que las peticiones GET escriban nada, solo que devuelvan datos.

Paquetes precargados

Las funciones sin servidor de HubSpot vienen actualmente precargadas con los siguientes paquetes: Para utilizar la última versión compatible de un paquete precargado, o para utilizar un paquete recién agregado:
  1. Clona o copia tu archivo de funciones.
  2. Cambia el endpoint de tu función en el archivo serverless.json para que se dirija a tu nuevo archivo de función. Puedes eliminar la versión antigua con seguridad.
Si quieres incluir paquetes fuera del conjunto de paquetes precargados, puedes usar webpack para combinar tus módulos de node y hacer que tus archivos agrupados sean tus archivos de función.

Límites

Las funciones sin servidor están previstas para ser rápidas y tener un enfoque limitado. Para permitir llamadas y respuestas rápidas, las funciones sin servidor de HubSpot tienen los siguientes límites:
  • 50 secretos por cuenta.
  • 128 MB de memoria.
  • No más de 100 endpoints por cuenta de HubSpot.
  • Debes usar contentType application/json cuando se llama a una función.
  • Los registros de las funciones sin servidor se almacenan durante 90 días.
  • 6MB en una carga útil de invocación de AWS Lambda.
Límites de ejecución
  • Cada función tiene un tiempo máximo de ejecución de 10 segundos
  • Cada cuenta está limitada a un total de 600 segundos de ejecución por minuto.
Esto significa que cualquiera de estos escenarios puede ocurrir:
  • 60 ejecuciones de funciones que tardan 10 segundos cada una en completarse.
  • 6000 ejecuciones de funciones que tardan 100 milisegundos en completarse.
Las funciones que superen esos límites arrojarán un error. El recuento de ejecuciones y los límites de tiempo devolverán una respuesta 429. El tiempo de ejecución de cada función se incluye en los registros de funciones sin servidor. Para ayudar a evitar estos límites, los datos de los límites se proporcionan automáticamente al contexto de la función durante la ejecución. Puedes utilizarlo para influir en tu solicitud para mantenerse dentro de esos límites. Por ejemplo, si tu aplicación requiere sondear tu endpoint, entonces puedes devolver con tus datos una variable para influir en la frecuencia del sondeo. De este modo, cuando el tráfico es elevado, se puede reducir el ritmo de sondeo para evitar que se alcancen los límites, y luego volver a aumentarlo cuando el tráfico sea escaso.