Skip to main content
Last modified: November 18, 2025
This feature requires approval from HubSpot to use. If you’re interested in applying to get access to app events, or if you want to learn more about the functionality, please submit this in-app form.
To send app event data to HubSpot, you’ll first create an event type using a developer project. The event type is a JSON schema that defines the structure, properties, and validation rules for the event occurrence data you’ll be sending. This includes the event name, display label, target CRM object, and event properties. Event types also include definitions for display templates for CRM record timeline rendering.
The app events described in this documentation are intended for apps built for the App Marketplace using developer projects. To build custom event reporting for other types of integrations, you can instead use custom events.

​
Prerequisites

To include an app event type definition in your project:
  • You must be using HubSpot CLI version 7.6.0 or later. You can check which version of the CLI you have by running hs --version, and update by running npm install -g @hubspot/cli@latest.
  • Your project must be deployed before you can update it to include an app event component.

​
Set up your project files

If you previously created a public app with a timeline event, learn more about migrating it to the developer platform.
1

App configuration and project structure

To create a new app event type definition in your project, update your app configuration hsmeta.json file to include the timeline scope in the requiredScopes field. This is required for app event data to appear on CRM record timelines. Installers must grant this scope for your event data to send successfully.
"requiredScopes": [
  "timeline"
],
Note that you may need to add other scopes, depending on the features your app includes.
Then, in the app/ directory of your project, add an app-events directory. In app-events/, add a JSON configuration file to define the app event type. This file can have any name, but must end in *-hsmeta.json. You can include up to 750 event types per app, with each having its own *-hsmeta.json file.
project-folder/
└── src/
    └── app/
        ├── app-hsmeta.json
        └── app-events/
            └── my-event-type-hsmeta.json
2

Configure the event type schema

In the event type *-hsmeta.json file, set up your event type schema. This schema will configure event type attributes such as name, CRM record timeline display template, and the CRM object type to associate event data with.While some of these fields can be updated after creation, the name and objectType fields cannot be changed once the event type is created.For example, the following event type schema could be used for tracking customer login events.
{
  "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"
          }
        ]
      }
    ]
  }
}

Fields marked with * are required.

FieldTypeDescription
uid*StringAn internal unique identifier for the event type.
type*StringThe type of component. Must be app-event.
name*StringThe label displayed in HubSpot (up to 50 characters). This value cannot be updated after creation.
objectType*StringThe fully qualified name of the CRM object type that event occurrences can be associated with. This value cannot be changed after creation. Can be one of: COMPANY, CONTACT, DEAL, TICKET, APP_OBJECT. To create an event type for custom objects, use the supportsCustomObject field instead.
supportsCustomObjectBooleanSet to true to configure the app event type for custom objects. When set to true:
  • The event type will be enabled for all custom objects in the account.
  • You cannot specify another objectType in addition to custom objects (i.e., the objectType cannot be set to CONTACT and support custom objects).
  • You cannot copy event property values to object property values via property stamping.
headerTemplateStringThe rendering template for the header of the CRM timeline activity card. Can be up to 1,000 characters in length.
detailTemplateStringThe rendering template for the body of the CRM timeline activity card. Can be up to 10,000 characters in length.
propertiesArrayProperties defined for the event type that you’ll store event occurrence data in. Each event type can have up to 500 properties. Learn more about properties, including requirements and limitations, in the app events reference documentation.
3

Upload your changes to HubSpot

Upload your project to HubSpot with the hs project upload command.
hs project upload
During the build phase, HubSpot will validate the event type. If there are any schema validation errors, the CLI will return an error indicating what to fix.By default, after a successful build, HubSpot will automatically deploy the project. If you’ve turned this off in your project settings, you can manually deploy using hs project deploy.After deploying, your app event type will now be available and can be used for receiving event occurrence data.

​
Retrieve the fullyQualifiedName

To send event occurrence data for the event type, you’ll need to retrieve the fullyQualifiedName via the app events API. This name identifies the event type, and will need to be included with all app event API operations. To retrieve the eventTypeName, make a POST request to https://api.hubapi.com/integrators/timeline/v4/types/projects. In the request body, include:
  • A projectName field, which should be set to the name value from the hsproject.json file of your project.
  • A developerSymbol field, which should be set to the uid value from the event type *-hsmeta.json configuration file.
{
  "projectName": "my-marketplace-app",
  "developerSymbol": "customer_login_event"
}
The response will return the project name, event type name, and the fullyQualifiedName. 
{
  "developerQualifiedSymbol": {
    "projectName": "marketplace",
    "developerSymbol": "customer_login_event"
  },
  "fullyQualifiedName": "ae000000_integrators-timeline-event-type-id-0000000"
}
The fullyQualifiedName value will never change, so you can safely hard code it into your implementation. The API limits the number of times you can retrieve this value per day, and cannot be used programmatically.

​
Managing event types

To update an event type after creation, you’ll just need to update the event type schema in your project, then re-upload to build and deploy the app. If you no longer wish to use an event type, you can delete it from your project. However, before deleting an event type, note the following:
  • Deleting an event type is a permanent and irreversible action.
  • Deleting an event type removes both the event type and all occurrences of that type from all accounts that have installed the app.
  • Deleting an event type will break other HubSpot tools that rely on that event type, such as reports and workflows. To delete the event type, delete the *-hsmeta.json event type configuration file from your project, then upload and deploy the project.

​
Migrate an existing timeline event type

If you have an existing public app with a timeline event, you can migrate it to the developer platform using the CLI.
Before migrating your app:
  • Check out the public app migration guide to review the current considerations and limitations of the developer platform beta.
  • Once you’ve migrated an existing timeline event type (v1/v3) to the developer platform, you’ll have 7 days to change existing v1/v3 timeline event API requests to the new v4 endpoints, including both event type event occurrence/instance API requests. After 7 days, any existing calls to v1/v3 event occurrence endpoints will return 401 errors.
    • For creating and updating event types and templates, you’ll no longer need to use the API. Instead, you’ll manage them directly in the project via the event type configuration file.
    • For sending event occurrence data, you’ll need to use the v4 endpoints, which offers both single and batch send endpoints.
To migrate your app:
  • In the terminal, run hs app migrate, then follow the terminal prompts to migrate your app and timeline event.
  • Once the migration process is done, your app will now live in a developer project, and a local project directory will be created for you.
  • To open the project in HubSpot, navigate into the local project directory, then run hs project open.
Note that the generated configuration files (*-hsmeta.json) may contain fields with null values. These fields are an artifact from the migration, and it’s safe to remove them.

​
Next Steps

After creating an event type, learn how to send event occurrence data via the API. You can also check out the app events reference documentation to continue building and customizing your app events.