HubSpot
Server-side event delivery to HubSpot via the official @hubspot/api-client SDK. Sends custom behavioral events, upserts contacts via the CRM API, and supports optional batch mode with graceful shutdown.
HubSpot is a server destination in the walkerOS flow:
Receives events server-side from the collector, resolves contact identity (email or objectId), optionally upserts contact properties, then sends the custom event to HubSpot.
Installation
- Integrated
- Bundled
Configuration
This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.
Settings
| Property | Type | Description | More |
|---|---|---|---|
accessToken | string | HubSpot private app access token. Create one in HubSpot Settings > Integrations > Private Apps. Requires analytics.behavioral_events.send scope. | |
eventNamePrefix | string | Fully qualified event name prefix: pe{HubID}_ (e.g. pe12345678_). Find it in HubSpot under Data Management > Custom Events. | |
email | string | walkerOS mapping value path to resolve contact email from events (like user.email). Required for contact association. | |
objectId | string | walkerOS mapping value path to resolve HubSpot CRM objectId from events. Alternative to email for contact association. | |
identify | any | Destination-level contact upsert mapping. Resolves to { email, properties }. Fires contact update on first push and re-fires when values change. | |
defaultProperties | Record<string, string> | Static event properties added to every event occurrence. Useful for hs_touchpoint_source, hs_page_content_type, etc. | |
batch | boolean | Use batch API for events (accumulate and flush). Default: false. | |
batchSize | integer | Batch size before auto-flush. Only used when batch: true. Default: 50. Max: 500. |
Mapping
Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.
| Property | Type | Description | More |
|---|---|---|---|
eventName | string | Override eventName for this rule. Without the prefix -- just the event name part (e.g. purchase_completed). The eventNamePrefix is prepended automatically. | |
identify | any | Per-event contact upsert. Resolves to { email, properties }. Overrides destination-level identify. Use with skip: true on login/identify events. | |
properties | any | Additional event properties mapping. Resolved values are merged with defaultProperties and serialized to strings. |
Examples
Default event
A walker event is sent to HubSpot as a custom behavioral event keyed by the user email.
Default properties
Destination-level default properties are merged into every HubSpot event payload, such as traffic source metadata.
Destination identify
Destination-level identify upserts the HubSpot contact with mapped properties before sending the behavioral event.
Custom event name
A mapping supplies a custom HubSpot event name and maps order data into properties for the behavioral event.
Object id association
The HubSpot event is associated via objectId instead of email, resolved from the walker user id.
User login identify
A user login only upserts the HubSpot contact with profile and lifecycle properties, skipping the event send.
Every event must be associated with a contact via email or objectId. The email path defaults to user.email. Events where neither value can be resolved are skipped with a warning.
Contact upsert
Use the identify setting (destination-level or per-rule) to upsert HubSpot contact properties alongside event tracking. The resolved mapping must produce { email, properties }. State-based dedup prevents redundant API calls when identity has not changed.