Última modificación: 11 de septiembre de 2025
Para enviar datos de eventos de la aplicación a HubSpot, primero crearás un tipo de evento utilizando un proyecto de desarrollador. El tipo de evento es un esquema JSON que define la estructura, las propiedades y las reglas de validación de los datos de ocurrencia del evento que vas a enviar. Esto incluye el nombre del evento, la etiqueta de visualización, el objeto del CRM de destino y las propiedades del evento. Los tipos de evento también incluyen definiciones de plantillas de visualización para la representación de la cronología de los registros del CRM.
Los eventos de aplicación descritos en esta documentación están pensados para aplicaciones creadas para el mercado de aplicaciones mediante proyectos de desarrollador. Para crear informes de eventos personalizados para otros tipos de integraciones, puedes utilizar eventos personalizados.

​
Requisitos previos

Para incluir una definición de tipo de evento de aplicación en tu proyecto:
  • Debes estar utilizando la CLI de HubSpot versión 7.5.4 o posterior. Puedes comprobar qué versión de la CLI tienes ejecutando hs --version, y actualizarla ejecutando npm i -g @hubspot/cli@next.
  • Tu proyecto debe estar implementando antes de que puedas actualizarlo para incluir un componente de eventos de aplicación.

​
Configurar los archivos del proyecto

Si anteriormente creaste una aplicación pública con un evento de cronología, obtén más información sobre cómo migrarla a la plataforma para desarrolladores.
1

Configuración de la aplicación y estructura del proyecto

Para crear una nueva definición de tipo de evento de aplicación en tu proyecto, actualiza el archivo hsmeta.json de configuración de la aplicación para incluir el permiso timeline en el campo requiredScopes. Esto es necesario para que los datos de los eventos de la aplicación aparezcan en las cronologías de los registros del CRM. Los instaladores deben conceder este permiso para que tus datos de eventos se envíen correctamente.
"requiredScopes": [
  "timeline"
],
Ten en cuenta que puede que necesites agregar otros permisos, dependiendo de las funciones que incluya tu aplicación.
A continuación, en el directorio app/ de tu proyecto, agrega un directorio app-events. En app-events/, agrega un archivo de configuración JSON para definir el tipo de evento de la aplicación. Este archivo puede tener cualquier nombre, pero debe terminar en *-hsmeta.json. Puedes incluir hasta 750 tipos de eventos por aplicación, y cada uno tiene su propio archivo *-hsmeta.json.
project-folder/
└── src/
    └── app/
        ├── app-hsmeta.json
        └── app-events/
            └── my-event-type-hsmeta.json
2

Configurar el esquema del tipo de evento

En el archivo de tipo de evento *-hsmeta.json, configura tu esquema de tipo de evento. Este esquema configurará los atributos del tipo de evento, como el nombre, la plantilla de visualización de la cronología del registro del CRM y el tipo de objeto del CRM al que asociar los datos del evento.Aunque algunos de estos campos pueden actualizarse después de la creación, los campos name y objectType no pueden modificarse una vez creado el tipo de evento.Por ejemplo, se podría utilizar el siguiente esquema de tipo de evento para hacer un seguimiento de los eventos de inicio de sesión de los clientes.
{
 "uid": "customer_login_event",
 "type": "app-event",
 "config": {
   "name": "Customer login",
   "headerTemplate": "{{customerName}} logged in",
   "detailTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
   "objectType": "CONTACT",
   "properties": [
     {
       "name": "customerName",
       "label": "Customer Name",
       "type": "string"
     },
     {
       "name": "loginLocation",
       "label": "Login location",
       "type": "enumeration",
       "options": [
         {
           "value": "mobileApp",
           "label": "Mobile app"
         },
         {
           "value": "website",
           "label": "Website"
         }
       ]
     }
   ]
 }
}

Los campos marcados con * son obligatorios.

CampoTipoDescripción
uid*CadenaUn identificador único interno para el tipo de evento.
type*CadenaEl tipo de componente. Debe ser app-event.
name*CadenaLa etiqueta que se muestra en HubSpot (hasta 50 caracteres). Este valor no se puede actualizar después de la creación.
objectType*CadenaEl nombre completo del tipo de objeto del CRM al que se pueden asociar los eventos. Este valor no se puede cambiar después de la creación. Puede ser uno de los siguientes: COMPANY, CONTACT, CUSTOM_OBJECT, DEAL, TICKET, APP_OBJECT.
headerTemplateCadenaLa plantilla de representación del encabezado de la tarjeta de actividad de la cronología del CRM. Puede tener hasta 1000 caracteres de longitud.
detailTemplateCadenaLa plantilla de representación para el cuerpo de la tarjeta de actividad de la cronología del CRM. Puede tener hasta 10.000 caracteres de longitud.
propertiesMatrizPropiedades definidas para el tipo de evento en el que vas a almacenar los datos de ocurrencia del evento. Cada tipo de evento puede tener hasta 500 propiedades. Más información sobre las propiedades, incluidos los requisitos y las limitaciones, en la documentación de referencia de los eventos de la aplicación.
3

Subir tus cambios a HubSpot

Sube tu proyecto a HubSpot con el comando hs project upload.
hs project upload
Durante la fase de construcción, HubSpot validará el tipo de evento. Si hay algún error de validación del esquema, la CLI devolverá un error indicando lo que hay que corregir.Por defecto, tras una compilación correcta, HubSpot implementará automáticamente el proyecto. Si lo has desactivado en la configuración del proyecto, puedes implementarlo manualmente utilizando hs project deploy.Tras la implementación, el tipo de evento de tu aplicación estará ahora disponible y podrá utilizarse para recibir datos de sucesos de eventos.

​
Recuperar el fullyQualifiedName

Para enviar los datos de ocurrencia del tipo de evento, tendrás que recuperar el fullyQualifiedName a través de la API de eventos de la aplicación. Este nombre identifica el tipo de evento, y deberá incluirse en todas las operaciones de la API de eventos de la aplicación. Para recuperar el eventTypeName, haz una solicitud POST a https://api.hubapi.com/integrators/timeline/v4/types/projects. En el cuerpo de la solicitud, incluye lo siguiente:
  • Un campo projectName, que debe ajustarse al valor name del archivo hsproject.json de tu proyecto.
  • Un campo developerSymbol, que debe ajustarse al valor uid del archivo de configuración del tipo de evento *-hsmeta.json.
{
  "projectName": "my-marketplace-app",
  "developerSymbol": "customer_login_event"
}
La respuesta devolverá el nombre del proyecto, el nombre del tipo de evento y el fullyQualifiedName. 
{
  "developerQualifiedSymbol": {
    "projectName": "marketplace",
    "developerSymbol": "customer_login_event"
  },
  "fullyQualifiedName": "ae000000_integrators-timeline-event-type-id-0000000"
}
El valor fullyQualifiedName no cambiará nunca, por lo que puedes codificarlo con seguridad en tu implementación. La API limita el número de veces que puedes recuperar este valor al día, y no puede utilizarse mediante programación.

​
Gestión de tipos de eventos

Para actualizar un tipo de evento después de crearlo, solo tendrás que actualizar el esquema del tipo de evento en tu proyecto, y luego volver a subirlo para crear e implementar la aplicación. Si ya no quieres utilizar un tipo de evento, puedes eliminarlo de tu proyecto. Sin embargo, antes de eliminar un tipo de evento, ten en cuenta lo siguiente:
  • Eliminar un tipo de evento es una acción permanente e irreversible.
  • Eliminar un tipo de evento elimina tanto el tipo de evento como todas las ocurrencias de ese tipo de todas las cuentas que hayan instalado la aplicación.
  • Si eliminas un tipo de evento, se romperán otras herramientas de HubSpot que dependen de ese tipo de evento, como los informes y los workflows. Para eliminar el tipo de evento, borra el archivo de configuración del tipo de evento *-hsmeta.json de tu proyecto, luego sube e implementa el proyecto.

​
Migrar un tipo de evento de cronología existente

Si ya tienes una aplicación pública con un evento de cronología, puedes migrarla a la plataforma para desarrolladores utilizando la CLI.
Antes de migrar tu aplicación:
  • Consulta la guía pública de migración de aplicaciones para revisar las consideraciones y limitaciones actuales de la beta de la plataforma para desarrolladores.
  • Una vez que hayas migrado un tipo de evento de cronología existente (v1/v3) a la plataforma para desarrolladores, dispondrás de 7 días para cambiar las solicitudes existentes de la API de eventos de cronología v1/v3 a los nuevos endpoints v4, incluidas las solicitudes de la API de ocurrencia/instancia de ambos tipos de eventos. Transcurridos 7 días, cualquier llamada existente a los endpoints de ocurrencia de eventos v1/v3 devolverá errores 401.
Para migrar tu aplicación:
  • En la terminal, ejecuta hs app migrate, luego sigue las indicaciones del terminal para migrar tu aplicación y el evento de cronología.
  • Una vez finalizado el proceso de migración, tu aplicación estará ahora en un proyecto de desarrollador, y se creará un directorio de proyecto local para ti.
  • Para abrir el proyecto en HubSpot, navega hasta el directorio local del proyecto y ejecuta hs project open.
Ten en cuenta que los archivos de configuración generados (*-hsmeta.json) pueden contener campos con valores null. Estos campos son un artefacto de la migración, y es seguro eliminarlos.

​
Pasos siguientes

Después de crear un tipo de evento, aprende a enviar datos de ocurrencia de eventos a través de la API. También puedes consultar la documentación de referencia de los eventos de la aplicación para seguir creando y personalizando los eventos de tu aplicación.