HubSpot: Create — event Definitions create Event Definition

← Event definitions operations · Get started

Operation hubspot.event_definitions_create_event_definition

Provider route: POST /events/2026-09/event-definitions. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/hubspot with npm, or alter-sdk-hubspot with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { HubSpotIntegration } from "@alter-ai/hubspot";

async function execute(input: Parameters<HubSpotIntegration["eventDefinitions"]["createEventDefinition"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new HubSpotIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.eventDefinitions.createEventDefinition(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_hubspot import HubSpotIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = HubSpotIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.event_definitions.create_event_definition(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
body	Model	Required within parent	Expand Create — event Definitions create Event Definition — request body — body

Referenced models: Create — event Definitions create Event Definition — request body — body

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Update event definition — response body

Referenced models: Update event definition — response body

Schemas

48 more schemas are linked from the tables above, on the schema pages.

Create — event Definitions create Event Definition — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
customMatchingId	Model	Optional	Expand Update event definition — response body — custom Matching Id
description	string	Optional	A string providing a description of the event type.
includeDefaultProperties	boolean	Required within parent	A boolean indicating whether default properties should be included.
label	string	Required within parent	A string representing the label of the event type.
name	string	Optional	A string representing the name of the event type.
primaryObject	string	Optional	A string indicating the primary object associated with the event type.
propertyDefinitions	array	Required within parent	An array of property definitions, each represented by an ExternalBehavioralEventPropertyCreate object.
propertyDefinitions[]	Model	Each item	Expand Create Property — request body — body

Referenced models: Create Property — request body — body, Update event definition — response body — custom Matching Id

Update event definition — response body

Field	Type	Presence	Description and constraints
$	object	Root
archived	boolean	Required within parent	A boolean indicating whether the event type is archived.
associations	array	Required within parent	An array of association definitions related to the event type.
associations[]	Model	Each item	Expand Update event definition — response body — associations item
comboEventRules	Model	Optional	Expand Update event definition — response body — combo Event Rules
createdAt	string	Optional	A string representing the date and time when the event type was created, in ISO 8601 format. Format: date-time
createdUserId	JSON	Optional
createdUserId (anyOf 1)	integer	Alternative	An integer representing the ID of the user who created the event type. Format: int32
createdUserId (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
customMatchingId	Model	Optional	Expand Update event definition — response body — custom Matching Id
description	string	Optional	A string providing a description of the event type.
detailTemplate	string	Optional	The rendering template for the body of the CRM timeline activity card.
fullyQualifiedName	string	Required within parent	A string representing the fully qualified name of the event type.
headerTemplate	string	Optional	The rendering template for the header of the CRM timeline activity card.
id	string	Required within parent	A string representing the unique identifier of the event type.
labels	Model	Required within parent	Expand Update event definition — response body — labels
name	string	Required within parent	A string representing the name of the event type.
objectTypeId	string	Required within parent	A string representing the object type ID associated with the event type.
primaryObject	string	Optional	A string representing the primary object associated with the event type.
primaryObjectId	string	Optional	A string representing the ID of the primary object associated with the event type.
properties	array	Required within parent	An array of property objects associated with the event type.
properties[]	Model	Each item	Expand Create Property — response body
trackingType	string	Optional	A string indicating the tracking type of the event. Valid values include 'VISITED_URL', 'CLICKED_ELEMENT', 'CUSTOM_SCRIPT', 'MANUAL', 'IMPORT', 'PROPERTY_CHANGE', 'COMBO_EVENT'. Known values: APP_EVENT, AUTOCAPTURE_EVENT, CLICKED_ELEMENT, COMBO_EVENT, CUSTOM_SCRIPT, CUSTOM_SIGNAL, IMPORT, MANUAL, POLLING, PROPERTY_CHANGE, VISITED_URL, WEBHOOK
updatedAt	string	Optional	A string representing the date and time when the event type was last updated, in ISO 8601 format. Format: date-time
updatedUserId	JSON	Optional
updatedUserId (anyOf 1)	integer	Alternative	An integer representing the ID of the user who last updated the event type. Format: int32
updatedUserId (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Referenced models: Update event definition — response body — labels, Update event definition — response body — custom Matching Id, Update event definition — response body — combo Event Rules, Update event definition — response body — associations item, Create Property — response body

Create Property — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
description	string	Optional	A string providing additional information about the property.
label	string	Required within parent	A string representing the display name of the property. This field is required.
name	string	Optional	A string representing the unique name of the property.
options	array	Optional	An array of OptionInput objects that define the possible values for the property.
options[]	Model	Each item	Expand Create Property — request body — body options item
type	string	Required within parent	A string indicating the data type of the property. This field is required.

Referenced models: Create Property — request body — body options item

Update event definition — response body — custom Matching Id

Field	Type	Presence	Description and constraints
$	object	Root
primaryObjectRule	Model	Required within parent	Expand Update event definition — response body — custom Matching Id primary Object Rule

Referenced models: Update event definition — response body — custom Matching Id primary Object Rule

Update event definition — response body — labels

Field	Type	Presence	Description and constraints
$	object	Root
plural	string	Optional	The plural form of the label for the event type. This is a string.
singular	string	Required within parent	The singular form of the label for the event type. This is a string and is required.

Update event definition — response body — combo Event Rules

Field	Type	Presence	Description and constraints
$	object	Root
composingRules	array	Required within parent	An array of ComboEventRule objects that define the individual rules composing this branch.
composingRules[]	Model	Each item	Expand Update event definition — response body — combo Event Rules composing Rules item
operationType	string	Required within parent	The type of logical operation applied to the rule branches and composing rules. Valid values are 'AND' and 'OR'. Known values: AND, OR
ruleBranches	array	Required within parent	An array of nested ComboEventRuleBranch objects, allowing for hierarchical rule definitions.
ruleBranches[]	Model	Each item	Expand Update event definition — response body — combo Event Rules

Referenced models: Update event definition — response body — combo Event Rules composing Rules item, Update event definition — response body — combo Event Rules

Create Property — request body — body options item

Field	Type	Presence	Description and constraints
$	object	Root
description	string	Optional	A string providing additional information about the option.
displayOrder	integer	Required within parent	An integer indicating the order in which the option should be displayed relative to other options. Format: int32
hidden	boolean	Required within parent	A boolean indicating whether the option is hidden from view.
label	string	Required within parent	A string representing the display label for the option.
value	string	Required within parent	A string representing the unique value associated with the option.

Update event definition — response body — custom Matching Id primary Object Rule

Field	Type	Presence	Description and constraints
$	object	Root
eventPropertyName	string	Required within parent	The name of the property on the event that is used for resolution. It is a string.
targetObjectPropertyName	string	Required within parent	The name of the property on the target object that is used for resolution. It is a string.

Update event definition — response body — combo Event Rules composing Rules item property Filters item context

Field	Type	Presence	Description and constraints
$	object	Root
objectTypeId	string	Required within parent	A string that uniquely identifies the type of object to which the property filter is applied.

Policy, approvals and errors

SDK function policy ID: hubspot.event_definitions_create_event_definition. Catalog operation: event_definitions_create_event_definition. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["behavioral_events.event_definitions.read_write"]

Official provider source