Last modified: September 3, 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.
Using app events, you can send enriched activity data from your external systems directly into HubSpot. App event data is associated with CRM records, and can be used across HubSpot’s automation, analytics, and reporting tools. Below, learn more about how app events work. To start building app events into your project:
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.

​
How app events work

Events are data points that capture what occurred at a specific moment in time, often related to user actions, such as submitting a form, sending an SMS message, or viewing a page. Unlike CRM records, which are intended to show the current state of an entity, events can give you a better understanding of activity patterns, behavioral changes over time, and other trends.
App events are ideal when your data:
  • Represents actions or activities that happen repeatedly.
  • Needs to be analyzed for changes or volume over time.
  • Doesn’t require updating after creation.
At a high level, an app event consists of:
  • Event type definition: a JSON schema that defines the structure, properties, and validation rules for the event. 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. Event types are defined using developer projects.
  • Event occurrences: individual instances of events that contain actual data, validated against your event type schema. Event occurrence data is sent via the app events API, and includes the event type identifier, property values, timestamps and additional metadata, and CRM object reference data for CRM record association.
Timeline events vs. app eventsPreviously, HubSpot released timeline events to enable you to surface event data on CRM object timelines. App events allow for that same functionality across an expanded list of supported objects, while also being available in other HubSpot tools. App events also now have their own index page alongside custom events, providing a unified view of event activities.Existing timeline event integrations will continue to function and will be visible in the same places as app events. However, to create new event types or make changes to existing types, you must recreate it as an app event in your developer project.

​
Supported objects and tools

When defining an event type, you’ll configure it to associate with a specific CRM object, enabling you to tie event data to its source, such as the contacts who log in to your website. Event occurrences can then be associated with CRM records of that type. App events can be associated with the following CRM objects:
  • Contacts
  • Companies
  • Deals
  • Tickets
  • Custom objects
  • App objects
App events can be used in the following HubSpot tools:
  • Event management interface: view and analyze app event data in the custom events dashboard alongside custom event data by navigating to Data Management > Custom events in your account.
  • CRM record timelines: view chronological app event activity on the timelines of CRM records associated with event occurrences.
  • Reporting tools: use app event data to build custom reports, customer journey analytics, and datasets for analysis and visualization.
  • Lead scores, lists, and workflows: segment your CRM database using events for dynamic lists, lead scoring, and triggering workflows.

​
Best practices

When building event types:
  • Use clear, descriptive names for event types and properties, as they’ll appear as filters in workflows, lists, reports, and the custom events dashboard.
  • Choose appropriate property types (string, number, datetime, etc.) that match your data and enable proper filtering and analysis.
  • Include properties that will be useful for segmentation, reporting, and automation triggers (e.g., transaction amounts, user roles, action categories).
  • Design event types with reporting and workflow use cases in mind, considering how users will filter and group event data.
  • Avoid making breaking changes to existing event type schemas, as this can disrupt existing workflows and reports that depend on the event structure.
To maintain high quality event data:
  • Review any programmatic event occurrence data requests to ensure they will properly validate against your event type schema.
  • Use consistent formatting for event property values, especially for dates, numbers, and categorical data.
  • Ensure event occurrences are associated with valid CRM record IDs.
  • Monitor event submission success rates and error responses.
  • Regularly review event data on CRM record timelines and in the custom events dashboard for accuracy.
Optimize event submission performance by:
  • Batching multiple event occurrences in single API requests when possible (up to 500 events per batch).
  • Keeping event occurrence payloads lean by only including necessary property data.
  • Implementing exponential backoff retry logic for failed event submissions.

​
Limitations

Keep in mind the following limitations when planning and building app events.

​
Version requirements

  • App events can only be created through the latest version of the developer project platform (2025.2).
  • For existing event types, you can continue to use the v1 and v3 timeline events API. However, you cannot create new event types using the v1 and v3 APIs.
  • For existing event types that have been migrated to app events on the developer platform, see the migration restrictions for more information about accessing the legacy API versions.

​
Event type constraints

  • Event occurrences must conform to the defined event type schema or they will be rejected.
  • Some event type fields cannot be updated after the event type is created (e.g., name and objectType).
  • New event types are subject to a review process before they can be activated.

​
Data limitations

  • Individual properties are limited to 510KB, with total event size capped at 1MB.
  • App events are intended for App Marketplace providers, and will only work with apps configured to use OAuth authentication. Internal systems should instead use custom events.

​
Getting started

To get started working with app events, you’ll need to: