Create Timeline Event

Add custom events to the timeline of any HubSpot record - perfect for tracking activities that happen outside HubSpot. Common uses:

Log customer actions from your app (logins, feature usage, purchases)
Track external system events (support calls, shipping updates)
Record custom milestones (onboarding completed, renewal date)
Document important interactions (demo attended, contract signed)

Action type: hubspot.v2.create_timeline_event

What This Does (The Simple Version)

Think of this like adding a note to someone’s activity feed, but way more powerful. Instead of just text, you can log structured events that show up on contact, deal, or company timelines in HubSpot. Real-world example: A customer completes onboarding in your app. You create a timeline event on their contact record showing “Onboarding Completed” with details like completion date, steps finished, and time spent. Your sales team sees this in HubSpot and knows the customer is ready for upsell conversations.

How It Works

This action creates a custom event that appears on the timeline of a HubSpot record. You choose:

What record to add the event to (contact, deal, company, etc.)
Event type identifier (you create this)
Event details (title, description, timestamp)
Custom properties (optional - any additional data you want to track)

The event appears on the record’s timeline in HubSpot, just like emails, calls, and meetings.

Setting It Up

Step 1: Choose Target Object Type

Select which type of HubSpot record you want to add the timeline event to:

Contacts - Add event to a person’s timeline
Companies - Add event to an organization’s timeline
Deals - Add event to a deal’s timeline
Tickets - Add event to a ticket’s timeline

Choose the object type from the dropdown.

Step 2: Enter Target Object ID

In the “Target Object ID” field, enter the HubSpot ID of the record you want to add the event to. Usually you’ll insert a variable here:

Click the {} button
Select the object ID from a previous action:
- From a search: current_contact → hs_object_id
- From a lookup: found_deal → id
- From a webhook: contact_id (if provided)

Example: Click {} → select contact_record → id

Step 3: Enter Event Type

The “Event Type” is a unique identifier for this kind of event. This helps HubSpot group similar events together. Format: Use lowercase with underscores, like:

onboarding_completed
feature_activated
purchase_made
support_call_completed
renewal_reminder

Type directly in the field or click {} to insert a variable. Note: Use the same event type for similar events. For example, all “Feature Activated” events should use feature_activated so they’re grouped together on the timeline.

Step 4: Enter Event Title

The “Event Title” is the headline that appears on the timeline - like a subject line. Examples:

“Onboarding Completed”
“Feature Activated: Advanced Reporting”
“Purchase: Enterprise Plan”
“Support Call: Billing Question”

Type directly or click {} to insert variables. You can combine text and variables:

Type “Purchase: ” then click {} → select plan_name
Type “Feature Activated: ” then click {} → select feature_name

Step 5: Enter Event Description (Optional)

The “Event Description” provides additional details that appear when someone clicks the event on the timeline. Examples:

“Customer completed all 5 onboarding steps in 3 days”
“Activated Advanced Reporting feature on 2025-10-01”
“Upgraded from Starter to Enterprise plan, annual billing”

Type directly or click {} to insert variables with details. Leave blank if you don’t need additional description.

Step 6: Add Event Properties (Optional)

Click ”+ Add Property” if you want to attach custom data to this event. This is different from HubSpot properties. These are custom key-value pairs specific to this event. Format: Each property is key=value, one per line:

steps_completed=5
time_spent_minutes=45
completion_date=2025-10-01

Or use variables by clicking {} in the value field. Leave blank if you don’t need custom properties.

Step 7: Set Event Timestamp (Optional)

The “Event Timestamp” controls when the event appears on the timeline. Default: If you leave this blank, it uses the current time (right now). Formats supported:

ISO 8601: 2025-10-01T14:30:00Z
Date only: 2025-10-01 (assumes midnight)
US format: 10/01/2025
Timestamp in milliseconds: 1727790600000 (13 digits)
Timestamp in seconds: 1727790600 (10 digits)

Usually you’ll:

Leave blank to use “now”
Click {} to insert a date variable from your trigger or previous action
Type a specific date if logging a past event

Step 8: Name Your Output Variable

Give the event result a descriptive name in the “Output Variable Name” field. Good names:

onboarding_event
purchase_event
timeline_event
logged_activity

This variable contains the event ID and confirmation details.

What You Get Back

The action returns confirmation that the event was created, including the event ID. Example output saved to onboarding_event:

{
  "id": "evt_12345",
  "event_type": "onboarding_completed",
  "event_title": "Onboarding Completed",
  "event_description": "Customer completed all steps",
  "timestamp": 1727790600000,
  "object_id": "67890",
  "object_type": "contacts",
  "created_at": "2025-10-01T14:30:00Z",
  "properties": {
    "steps_completed": "5",
    "time_spent_minutes": "45"
  }
}

Using the Results

Confirm Event Was Created

The event either succeeds (returns event ID) or throws an error. The output variable contains the event ID, which you can use to verify creation succeeded.

Access Event Details

Use the output variable to access event information in later actions:

Click {} → onboarding_event → id (the event ID)
Click {} → onboarding_event → timestamp
Click {} → onboarding_event → properties → steps_completed

Common Workflows

Log App Activity

Goal: When a user completes onboarding in your app, log it on their HubSpot contact Trigger: Webhook from your app Webhook receives: contact_id, steps_completed, completion_time variables

Create Timeline Event (V2)
- Object Type: Contacts
- Target Object ID: Click {} → select contact_id
- Event Type: onboarding_completed
- Event Title: “Onboarding Completed Successfully”
- Event Description: Type “Completed ” then click {} → select steps_completed → type ” steps”
- Event Properties:
  steps_completed={{steps_completed}} time_spent_minutes={{completion_time}}
- Event Timestamp: Leave blank (use current time)
- Output Variable: onboarding_event
Update contact or send notification…

Track Purchase on Company Timeline

Goal: When a company makes a purchase, log it on their company record Trigger: Webhook from payment processor Webhook receives: company_domain, plan_name, amount, purchase_date

Lookup HubSpot Object (V2)
- Object Type: Companies
- Lookup by: Domain
- Domain: Click {} → select company_domain
- Output Variable: company_record
Create Timeline Event (V2)
- Object Type: Companies
- Target Object ID: Click {} → company_record → id
- Event Type: purchase_made
- Event Title: Type “Purchase: ” then click {} → select plan_name
- Event Description: Type “Purchased ” then click {} → select plan_name → type ” for $” → click {} → select amount
- Event Properties:
  plan_name={{plan_name}} amount={{amount}} billing_frequency=annual
- Event Timestamp: Click {} → select purchase_date
- Output Variable: purchase_event

Log Support Call on Deal

Goal: After a support call, log it on the related deal’s timeline

Search HubSpot (V2)
- Find the deal associated with the customer
- Output Variable: customer_deal
Create Timeline Event (V2)
- Object Type: Deals
- Target Object ID: Click {} → customer_deal → hs_object_id
- Event Type: support_call_completed
- Event Title: Type “Support Call: ” then click {} → select call_topic
- Event Description: Click {} → select call_notes
- Event Properties:
  duration_minutes={{call_duration}} resolution={{resolution_status}} agent={{support_agent_name}}
- Event Timestamp: Click {} → select call_time
- Output Variable: support_event

Real Examples

Feature Activation Tracking

Scenario: Track when customers activate premium features in your SaaS app. Webhook receives: user_email, feature_name, activation_date Timeline Event Configuration:

Object Type: Contacts
Target Object ID: Click {} → select contact_id (from lookup action)
Event Type: feature_activated
Event Title: Type “Feature Activated: ” then click {} → select feature_name
Event Description: Type “Customer activated ” then click {} → select feature_name → type ” on ” → click {} → select activation_date

Event Properties:

feature_name={{feature_name}}
plan_tier={{user_plan}}
activation_date={{activation_date}}

Event Timestamp: Click {} → select activation_date
Output Variable: feature_event

Next steps: Check if they’ve activated 3+ features and update lifecycle stage.

Renewal Reminder Logging

Scenario: Log when renewal reminders are sent to customers. Trigger: Scheduled (runs daily) Timeline Event Configuration:

Object Type: Deals
Target Object ID: Click {} → select current_deal → hs_object_id (from loop)
Event Type: renewal_reminder_sent
Event Title: “Renewal Reminder Sent”
Event Description: Type “Renewal reminder sent for contract ending ” then click {} → select contract_end_date

Event Properties:

contract_value={{deal_amount}}
days_until_renewal={{days_remaining}}
reminder_number={{reminder_count}}

Event Timestamp: Leave blank (current time)
Output Variable: reminder_event

Troubleshooting

”Target Object Not Found” Error

Error: Can’t find the object to add event to Possible causes:

Object ID is wrong or doesn’t exist
Variable containing ID is empty
Using wrong object type for that ID

How to fix:

Check the execution log - what ID was used?
Verify the object exists in HubSpot (search by ID)
Make sure previous action (lookup/search) found the record successfully
Check that object type matches the ID (contact ID needs object type = Contacts)

“Invalid Event Type” Error

Error: Event type format is incorrect Possible causes:

Event type contains spaces or special characters
Event type is empty

How to fix:

Use lowercase with underscores only: onboarding_completed not “Onboarding Completed”
No spaces, no special characters except underscore
Make sure the field isn’t empty

Events Not Showing on Timeline

Events created but don’t appear in HubSpot Possible causes:

Looking at wrong record
Timeline filtered to hide custom events
Timestamp is far in past/future

How to fix:

Verify you’re looking at the correct contact/company/deal in HubSpot
In HubSpot timeline, click “Filter” and make sure custom events are enabled
Check the timestamp - events in the far future or distant past might not show by default
Refresh the HubSpot page

Timestamp Not Parsing

Timestamp field showing current time instead of expected date Possible causes:

Date format not recognized
Variable is empty or has invalid value

How to fix:

Use one of the supported formats (ISO 8601 is most reliable: 2025-10-01T14:30:00Z)
Check execution log to see what value was sent
If using a variable, verify it contains a valid date
Leave blank to use current time

Tips & Best Practices

✅ Do:

Use consistent event types across workflows (helps with reporting)
Include meaningful descriptions that provide context
Set custom properties for data you’ll want to filter/report on later
Use descriptive event titles that make sense at a glance
Test with a single record before running on multiple records
Use past timestamps to backfill historical events

❌ Don’t:

Use spaces or special characters in event type (breaks filtering)
Create events without checking if target object exists first
Log too many events (clutters timeline) - be selective
Forget to include key context in description or properties
Use vague event types like “event1” or “update” (not helpful later)

Performance tips:

Creating timeline events is fast (under 1 second typically)
You can create many events in a loop without issues
Consider batching if creating thousands of events

What to do next:

Lookup HubSpot Object (V2) - Find object ID before creating event
Search HubSpot (V2) - Find multiple records to log events on
Get Timeline Events - Retrieve events from a record’s timeline
For Loop - Create events on multiple records

Related guides:

Variable System - Using variables in event properties
Webhook Triggers (HubSpot) - Triggering workflows from HubSpot

Last Updated: 2025-10-01

Using Agent.ai

For Builders

Actions

What This Does (The Simple Version)

How It Works

Setting It Up

Step 1: Choose Target Object Type

Step 2: Enter Target Object ID

Step 3: Enter Event Type

Step 4: Enter Event Title

Step 5: Enter Event Description (Optional)

Step 6: Add Event Properties (Optional)

Step 7: Set Event Timestamp (Optional)

Step 8: Name Your Output Variable

What You Get Back

Using the Results

Confirm Event Was Created

Access Event Details

Common Workflows

Log App Activity

Track Purchase on Company Timeline

Log Support Call on Deal

Real Examples

Feature Activation Tracking

Renewal Reminder Logging

Troubleshooting

”Target Object Not Found” Error

“Invalid Event Type” Error

Events Not Showing on Timeline

Timestamp Not Parsing

Tips & Best Practices

Using Agent.ai

For Builders

Actions

​What This Does (The Simple Version)

​How It Works

​Setting It Up

​Step 1: Choose Target Object Type

​Step 2: Enter Target Object ID

​Step 3: Enter Event Type

​Step 4: Enter Event Title

​Step 5: Enter Event Description (Optional)

​Step 6: Add Event Properties (Optional)

​Step 7: Set Event Timestamp (Optional)

​Step 8: Name Your Output Variable

​What You Get Back

​Using the Results

​Confirm Event Was Created

​Access Event Details

​Common Workflows

​Log App Activity

​Track Purchase on Company Timeline

​Log Support Call on Deal

​Real Examples

​Feature Activation Tracking

​Renewal Reminder Logging

​Troubleshooting

​”Target Object Not Found” Error

​“Invalid Event Type” Error

​Events Not Showing on Timeline

​Timestamp Not Parsing

​Tips & Best Practices

​Related Actions

What This Does (The Simple Version)

How It Works

Setting It Up

Step 1: Choose Target Object Type

Step 2: Enter Target Object ID

Step 3: Enter Event Type

Step 4: Enter Event Title

Step 5: Enter Event Description (Optional)

Step 6: Add Event Properties (Optional)

Step 7: Set Event Timestamp (Optional)

Step 8: Name Your Output Variable

What You Get Back

Using the Results

Confirm Event Was Created

Access Event Details

Common Workflows

Log App Activity

Track Purchase on Company Timeline

Log Support Call on Deal

Real Examples

Feature Activation Tracking

Renewal Reminder Logging

Troubleshooting

”Target Object Not Found” Error

“Invalid Event Type” Error

Events Not Showing on Timeline

Timestamp Not Parsing

Tips & Best Practices

Related Actions