HubSpot custom events

Send identified Nimriz conversions to a HubSpot custom behavioral event through managed OAuth.

Availability: HubSpot setup is available on Professional and Enterprise plans.

Requirements

• A Professional plan or higher.
• A HubSpot account that can use custom behavioral events.
• A defined custom event with a custom matching ID property.
• Customer conversion callbacks that include user_data.external_id.

Nimriz uses managed OAuth with the analytics.behavioral_events.send scope. Manual and private-app access tokens are not supported for this destination.

Prepare the HubSpot event

1. Define a HubSpot custom event and include an event property that will receive your customer identifier.
2. Configure that event property as the custom matching ID for the intended CRM object property.
3. Record the fully qualified event name. It has the form pe1234567_internal_event_name.
4. Record the event property's internal name, such as customer_external_id.

HubSpot's custom event definition guide explains custom matching IDs, and its send event guide describes event occurrences.

Connect HubSpot in Nimriz

1. Go to Integrations›Destinations›Browse catalog and choose HubSpot.
2. Enter the Fully qualified event name and Matching event property.
3. Select Save destination. Nimriz creates the destination disabled.
4. Open the destination and select Connect provider.
5. Authorize the HubSpot account that owns the custom event.
6. Enter a temporary Sample external ID and select Send test event. The value is not saved by Nimriz, but HubSpot receives a real test event occurrence.
7. After the test succeeds, turn on the destination enable switch. Enablement requires both a successful test for the latest stored event configuration and currently healthy authorization.

Changing the saved event name, matching property, or other stored connector configuration requires another successful test. Completing a new HubSpot authorization or reconnect also clears prior test readiness, so run another test before enabling.

Identity and payload behavior

Only conversions with a customer-supplied external_id qualify. Nimriz resolves that value immediately before dispatch and places it at properties[custom_matching_id_property]. It is not added to the canonical integration event and is not sent to analytics, alert, or warehouse destinations.

Clicks, scans, card events, anonymous activity, internal subject IDs, ip_hash, raw IP, and complete User-Agent strings are not sent to HubSpot.

Troubleshooting

• Event name rejected: use the fully qualified pe<HubID>_<internal_name> value, not the event label.
• Record not matched: confirm the configured event property and target CRM property form the custom matching ID.
• Reconnect required: reconnect HubSpot, confirm the connection is healthy, then run another test before enabling.
• Missing external ID: include user_data.external_id in the conversion callback. Nimriz suppresses the delivery safely without consuming destination volume.