HubSpot Object Merge Handling

When two Companies or two Contacts are merged in HubSpot, Magentrix detects the merge in real time via a HubSpot webhook, reassigns Magentrix records that referenced the secondary (merged-out) record to the surviving record, and deletes the Magentrix copy of the secondary. No administrator action is required.

Supported Object Types

• HubSpot Companies (Magentrix Accounts) — via the company.merge webhook event.
• HubSpot Contacts (Magentrix Contacts) — via the contact.merge webhook event.

HubSpot Deal merges are not handled by the integration.

How a Merge Is Detected

When you merge two records in HubSpot, HubSpot dispatches a webhook event (company.merge or contact.merge) to Magentrix. The payload lists the ID of the surviving record and the IDs of the merged-out records. Magentrix processes the event immediately — there is no scheduled-job delay.

What Happens During a Merge

1. The surviving record is created if needed. If the surviving HubSpot record does not yet have a Magentrix copy, Magentrix creates it before proceeding.
2. Lookup references are reassigned. Magentrix scans every entity in the tenant for lookup fields that point at the merged object type. Any record whose lookup value is one of the merged-out IDs is updated to point at the surviving record. This covers standard entities (Tasks, Events, Notes, Attachments, and any others with a lookup to the merged type) as well as any custom entity that references the type.
3. The secondary record is deleted. Once child references are reassigned, the Magentrix copy of each merged-out record is deleted so that only the surviving record remains.

Retroactive Processing on Upgrade

The webhook subscription for contact.merge was added in v2026.3.0. Contacts merged in HubSpot before that release did not produce Magentrix updates at the time. To close that gap, the upgrade to v2026.3.0 runs a one-time migration that queries HubSpot for previously-merged Contacts and processes them through the same pipeline described above. Administrators do not need to trigger this — it runs automatically on release install.

Primary Company Limitation

HubSpot allows a Contact to be associated with multiple Companies (one Primary, plus secondary associations). Magentrix stores a single Account per Contact, so the integration syncs only the Primary Company association after a merge. Secondary associations in HubSpot are ignored. If your business process needs multi-company visibility per contact, model it with a separate custom entity rather than expecting the Contact’s Account lookup to reflect secondaries.

Audit and Troubleshooting

Each step of the merge — creating the surviving record, editing child references, and deleting the secondary — is executed in its own transaction and logged. If a delete or edit fails (for example, because a foreign-key constraint or validation rule prevents the update), the failure is recorded as an error in the system event log with the merge context. The rest of the merge continues; individual failures do not abort the whole batch.

When investigating an incomplete merge, look in the system event log for entries that reference MergeHubspotObjects. The log entry includes the merged and surviving record IDs so you can locate the specific rows in Magentrix.

<< Activating and Mapping HubSpot Entities | Troubleshooting >>