HubSpot WordPress Integration:
Sync Contact on User Register

HubSpot's contacts API has two write endpoints. POST /contacts always creates a new record — useless if the same email registers twice (or matches an existing CRM record from a prior touchpoint). POST /contacts/batch/upsert uses an idProperty (we'll use email) to match existing records: it returns the existing contact_id if found, creates a new one if not. results[0].new tells us which case fired. That's the right shape for "one HubSpot contact per real-world person".

Why hook user_register and not the WC order trigger? Because Part 5's order chain self-heals for new emails by upserting in-chain. An order-time contact webhook would be doing the same work twice for first orders and would race with the deal-create chain. The cleaner split: register-time syncs the contact identity once, order-time relies on the chain to fill in the gap if it doesn't find one.

Some programmatic user creation paths (CLI imports, partial migrations) can land without a usable email. Without that we can't upsert — skip the dispatch cleanly. The pre-glue's idempotency guard handles re-fires (e.g. user-meta already populated), this condition handles the "no email at all" edge case.

Test 1 — new user registers. Use any path that creates a WP user with a fresh email: WP admin "Add New User", a registration form plugin, the WC account checkbox at checkout, or directly via WP-CLI: wp user create test1234 [email protected] --first_name=Test --last_name=User --role=customer. Webhook Actions log shows webhook 56 returning 200 with "results":[{...,"new":true}]. HubSpot → CRM → Contacts shows the new entry. WP user_meta has _hubspot_contact_id populated.

Test 2 — existing HubSpot email. Register a WP user with an email that already exists in HubSpot (e.g. an email from a prior marketing-form submission). Webhook Actions log shows webhook 56 returning 200 with "results":[{...,"new":false}] — HubSpot returned the existing contact_id rather than creating a duplicate. user_meta is populated with that existing contact_id; lifecyclestage is overwritten to "lead" (revisit this if it's a regression for your pipeline — see Pitfalls).

Test 3 — re-fire idempotency. For the same WP user, run do_action('user_register', $user_id, []) manually (via WP-CLI wp eval). Pre-glue detects user_meta._hubspot_contact_id is already set, returns {"inputs":[]}, condition inputs.0.properties.email is_not_empty fails — webhook is skipped with no HubSpot call. Status in the log: skipped. No duplicate work.

Confirm the Part 5 hand-off. Now place a WC order using the same user. Filter Logs by chain HS - Order Line Items: you should see Webhook 54 (HS - Associate Existing Contact, chain link 12) fire with status success 200, and Webhook 55 (HS - Upsert Contact) skipped — Condition not met: _hubspot_contact_id is_empty. That's the proof Part 4 paid off — one HubSpot call for the association instead of two.

Using POST /contacts instead of /contacts/batch/upsert. Plain POST creates duplicates if the email already exists in HubSpot. The single-record /contacts/upsert?idProperty=email URL you might find in older blog posts returns 405 Method Not Allowed — it doesn't exist in the 2026-03 API. Always batch/upsert.

Forgetting the "id" field inside inputs[]. The batch/upsert input requires both idProperty: "email" AND id: "<email value>" at the input root. HubSpot uses id as the lookup key value and ignores it from properties. Omitting it returns 400.

Re-firing user_register breaks the contact. Some plugins re-fire the action when updating user roles or syncing from external systems — without the pre-glue idempotency guard (user_meta._hubspot_contact_id already set → return empty inputs), every re-fire is a full overwrite of HubSpot properties. Test re-fires explicitly before going live.

Lifecyclestage overwrite on re-fire. Setting lifecyclestage = "lead" on every upsert can downgrade a contact already at "customer" or "opportunity" stage. HubSpot's stage progression is monotonic by default (lead → customer is allowed, customer → lead is silently dropped), but custom property settings can break that. The pre-glue idempotency guard avoids the overwrite entirely for previously-synced users. For first-time users with a pre-existing HubSpot record at a later stage, you may want to omit the lifecyclestage property from the upsert payload.

Email collision with existing HubSpot records. Upsert by email returns the existing contact_id silently if found — great for dedupe, occasionally surprising if the registering user happens to share an email with an unrelated CRM record (typo, shared inbox, signed up under a coworker's email). user_meta gets the existing contact_id, Part 5 wires the deal to that contact. Usually fine; review your CRM hygiene if cross-contamination is a worry.

Programmatic user creation skips first_name/last_name. wp_insert_user() with just user_email + user_login creates a user with empty first_name/last_name user_meta. The pre-glue falls back to splitting display_name — but if that's also blank, the HubSpot contact lands with empty name fields. Either fill the names at registration or accept the empty-name records.