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
default properties
destination identify
mapped event name
no identity
object id association
user login identify
wildcard ignored
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.