Última modificación: 22 de agosto de 2025
Los eventos personalizados te permiten definir y hacer un seguimiento de eventos exclusivos de tu empresa, como eventos en tu sitio web o en una aplicación. Puedes configurar eventos para almacenar información dentro de las propiedades, que luego podrás utilizar en todas las herramientas de HubSpot. Para enviar los datos del evento personalizado a HubSpot, primero tienes que definir el evento. Esto es similar a los objetos personalizados del CRM, donde primero tienes que definir el objeto personalizado antes de poder crear registros individuales para ese objeto. La definición de un evento incluye detalles como sus metadatos, asociaciones de objetos del CRM y propiedades. A continuación, obtén más información sobre cómo crear y gestionar definiciones de eventos utilizando la API. Para aprender a crear definiciones de eventos sin utilizar la API, consulta la base de conocimientos de HubSpot.

​
Crear una definición de evento

Para crear el esquema de evento personalizado, haz una solicitud POST a events/v3/event-definitions. En el cuerpo de la solicitud, incluye definiciones para tu esquema de eventos, incluyendo su etiqueta, nombre, asociaciones de objetos del CRM y propiedades personalizadas. El cuerpo de la solicitud que aparece a continuación proporciona un ejemplo básico de definición de un evento: 
{
  "label": "My event label",
  "name": "unique_event_name",
  "description": "An event description that helps users understand what the event tracks.",
  "primaryObject": "COMPANY",
  "propertyDefinitions": [
    {
      "name": "choice-property",
      "label": "Choice property",
      "type": "enumeration",
      "options": [
        {
          "label": "Option 1",
          "value": "1"
        },
        {
          "label": "Option 2",
          "value": "2"
        }
      ]
    },
    {
      "name": "string-property",
      "label": "String property",
      "type": "string"
    }
  ],
  "includeDefaultProperties": true
}
Si quieres vincular automáticamente las finalizaciones de eventos a registros de un tipo de objeto del CRM específico, puedes incluir un customMatchingId en tu solicitud POST. Dentro de este campo, define un objeto primaryObjectRule con dos campos: la propiedad única del objeto que has configurado previamente como targetObjectPropertyName y una de las propiedades que has definido en propertyDefinitions a partir de la definición de tu evento. Por ejemplo, el siguiente cuerpo de solicitud especifica un customMatchingId que coincide con un nombre de propiedad de objeto del CRM de "unique_object_property" y el nombre de propiedad de evento de "string_property": 
{
  "label": "My event label",
  "name": "unique_event_name",
  "description": "An event description that helps users understand what the event tracks.",
  "primaryObject": "COMPANY",
  "propertyDefinitions": [
    {
      "name": "string-property",
      "label": "String property",
      "type": "string"
    }
  ],
  "customMatchingId": {
    "primaryObjectRule": {
      "targetObjectPropertyName": "unique_object_property",
      "eventPropertyName": "event_property"
    }
  }
}
La lista completa de parámetros disponibles para el cuerpo de la solicitud se detalla en la tabla siguiente:
ParámetroTipoDescripción
labelCadenaLa etiqueta legible del evento, que se mostrará en HubSpot (hasta 100 caracteres). Las etiquetas largas pueden aparecer cortadas en algunas partes de la interfaz de usuario de HubSpot.
nameCadenaEl nombre interno y único del evento, que utilizarás para hacer referencia al evento a través de la API. Si no se proporciona ningún valor, HubSpot generará uno automáticamente basándose en la etiqueta.
  • Esta propiedad no puede modificarse una vez creada la definición del evento.
  • Esta propiedad solo puede contener letras minúsculas, números, guiones bajos y guiones (hasta 50 caracteres).
  • El primer carácter debe ser una letra.
descriptionCadenaLa descripción del evento, que se mostrará en HubSpot.
primaryObjectCadenaEl tipo de objeto del CRM al que se asociarán los datos del evento. Las finalizaciones de eventos aparecerán en los registros del CRM de ese tipo de objeto. Puede ser uno de los siguientes: "CONTACT" (predeterminado), "COMPANY", "DEAL", "TICKET", "<CUSTOM_OBJECT_NAME>". Este no se puede modificar después de crear la definición del evento.
propertyDefinitionsMatrizAdemás de las propiedades de evento predeterminadas de HubSpot, puedes incluir esta matriz para definir propiedades de evento personalizadas (hasta 50). Para cada objeto propiedad, incluye los siguientes campos:
  • name: el nombre interno de la propiedad, que utilizarás cuando envíes datos de eventos a través de la API.
  • label: la etiqueta en la aplicación de la propiedad.
  • type: el tipo de propiedad. De forma predeterminada es string.
  • options: para las propiedades de tipo enumeration, esta matriz define los valores disponibles. Debe incluir un label y un value para cada opción.
  • description: texto que describe la propiedad.
customMatchingIdObjetoComo alternativa a incluir el objectId del objeto de destino en los datos de finalización del evento, este campo opcional define una regla para vincular automáticamente las finalizaciones de eventos a registros del tipo de objeto del CRM especificado. Esto se hace haciendo coincidir el valor de una propiedad de los datos del evento con el valor de una propiedad única del objeto de destino. Este objeto debe incluir un objeto anidado primaryObjectRule, que a su vez debe incluir dos campos:
  • targetObjectPropertyName: una cadena que especifica el nombre de la propiedad única en el objeto del CRM de destino que se utilizará para la asignación.
  • eventPropertyName: una cadena que especifica el nombre de la propiedad en los datos del evento personalizado que se utilizará para la asignacicón.
includeDefaultPropertiesBooleanoCampo opcional que especifica si el evento debe incluir el conjunto de propiedades predeterminadas del evento. Si no se proporciona ningún valor, este campo se establecerá automáticamente como true.

​
Propiedades de eventos

Las propiedades de evento personalizado se utilizan para almacenar información sobre la finalización de eventos personalizados individuales. Estas propiedades deben utilizarse cuando sea apropiado para enviar finalizaciones de eventos, pero no son necesarias para que una finalización de evento sea válida. Para cada definición de evento, HubSpot proporciona un conjunto predeterminado de 32 propiedades. Además, puedes crear hasta 50 propiedades personalizadas por definición de evento. Las propiedades pueden ser de los siguientes tipos:
  • bool: propiedad que recibe un valor booleano. Los valores deben representarse como true o false.
  • date: propiedad que recibe una fecha que representa un día, un mes y un año específicos. Los valores deben estar en la zona horaria UTC y el formato puede ser una cadena en notación ISO 8601 o una marca de tiempo EPOCH en milisegundos (es decir, la media noche en la zona horaria UTC).
  • datetime: Propiedad que recibe valores en milisegundos de epoch o ISO8601 que representan una marca de tiempo.
  • enumeration: Una propiedad con opciones predefinidas. Al crear este tipo de propiedad, incluye una matriz options para establecer los valores disponibles.
  • number: propiedad que recibe valores numéricos con hasta un decimal.
  • string: una propiedad que recibe cadenas de texto sin formato. Si el nombre de la propiedad contiene las palabras url, referrer, o link, el valor de propiedad puede tener hasta 1024 caracteres. De lo contrario, los valores de propiedad pueden tener hasta 256 caracteres.
A continuación, obtén información sobre las propiedades del evento predeterminadas de HubSpot, sobre cómo definir nuevas propiedades para eventos existentes, y sobre cómo actualizar las propiedades personalizadas del evento existentes.

​
Propiedades del evento predeterminadas de HubSpot

  • hs_asset_description
  • hs_asset_type
  • hs_browser
  • hs_campaign_id
  • hs_city
  • hs_country
  • hs_device_name
  • hs_device_type
  • hs_element_class
  • hs_element_id
  • hs_element_text
  • hs_language
  • hs_link_href
  • hs_operating_system
  • hs_operating_version
  • hs_page_content_type
  • hs_page_id
  • hs_page_title
  • hs_page_url
  • hs_parent_module_id
  • hs_referrer
  • hs_region
  • hs_screen_height
  • hs_screen_width
  • hs_touchpoint_source
  • hs_tracking_name
  • hs_user_agent
  • hs_utm_campaign
  • hs_utm_content
  • hs_utm_medium
  • hs_utm_source
  • hs_utm_term

​
Definir nuevas propiedades

Para definir una nueva propiedad en un evento personalizado existente, haz una solicitud POST a events/v3/event-definitions/{eventName}/property. En el cuerpo de la solicitud, incluye la definición de tu propiedad. 
{
  "name": "property-name",
  "label": "Property name",
  "type": "enumeration",
  "options": [
    {
      "label": "label",
      "value": "value"
    }
  ]
}
Cuando pongas nombre a tu propiedad, ten en cuenta lo siguiente:
  • Una vez que creas una propiedad, su nombre no se puede cambiar.
  • El nombre solo puede contener letras minúsculas, números, guiones bajos y guiones.
  • El primer carácter del nombre de propiedad debe ser una letra.
  • El nombre de propiedad y la etiqueta pueden tener hasta 50 caracteres cada uno.
  • Si no se proporciona un nombre de propiedad, se autogenerará uno utilizando la etiqueta de la propiedad.
  • Las etiquetas largas pueden quedar cortadas en algunas partes de la interfaz de HubSpot.

​
Actualizar propiedades personalizadas existentes

Para actualizar una propiedad existente en un evento personalizado, haz una solicitud PATCH a events/v3/event-definitions/{eventName}/property. Los únicos campos que se pueden actualizar en una propiedad son los de label, description, y options para las propiedades de enumeración.

​
Nota:

Para cambiar el tipo de propiedad, utiliza el interruptor DELETE para eliminar la propiedad y volver a crearla con el tipo correcto.

​
Eliminar una propiedad

Para eliminar una propiedad existente en un evento personalizado, haz una solicitud DELETE a events/v3/event-definitions/{eventName}/property/{propertyName}. Cuando se elimina una propiedad, ya no estará disponible para su uso en futuras finalizaciones de eventos. Las finalizaciones anteriores seguirán teniendo los valores de propiedad.

​
Actualizar un evento

Para actualizar un esquema de evento personalizado existente, haz una solicitud PATCH a events/v3/event-definitions/{eventName}. Los únicos campos de definición de eventos que se pueden actualizar son label y description. 
{
  "label": "Event label",
  "description": "A description of the event"
}

​
Eliminar un evento

Para eliminar un evento personalizado, haz una solicitud DELETE a events/v3/event-definitions/{eventName}. Al eliminar un evento personalizado, se eliminará de cualquier otra herramienta de HubSpot que haga referencia a él, como workflows e informes.

​
Ten en cuenta que cuando elimines un evento:

  1. Todos los eventos de esa definición de evento se eliminarán y serán irrecuperables.
  2. Los eventName borrados previamente no se pueden volver a utilizar, así que ten cuidado al borrar un evento.

​
Obtener definiciones de eventos existentes

Para obtener una única definición de evento, haz una solicitud GET a events/v3/event-definitions/{eventName}. Para buscar definiciones de eventos por criterios específicos, haz una solicitud GET a events/v3/event-definitions. Puedes proporcionar los siguientes parámetros de consulta para ajustar tu búsqueda:
  • searchString: busca eventos que contengan los caracteres especificados en el campo name. La búsqueda no es difusa, sino que se trata de una búsqueda simple que verifica si el término está contenido.
  • after: una cadena con hash proporcionada en las respuestas paginadas para visualizar la siguiente página de los resultados de la búsqueda.
  • limit: el número máximo de resultados a devolver.
  • includeProperties: un valor booleano que especifica si se incluyen propiedades del evento en los resultados devueltos.