HubSpot + vtenext integration

vtenext comes out of Italy: an open source CRM with a BPMN process engine built in, made by a software house headquartered in Verona with offices in Milan and London, and run either on premise or in vtenext’s cloud. This page is written for one situation in particular, a North American or European team selling in HubSpot while a parent company’s vtenext holds the customer record, the quotes, the orders and the invoices.

vtenext already ships part of the answer. Its Synchronizations settings, under the business process manager, include HubSpot for accounts, contacts, potentials, trouble tickets, targets and users, and the synchronization runs on vtenext’s scheduler, every minute by default. For a team that needs those modules and nothing more, that is the first thing to try, and it costs configuration rather than a build.

It stops short of the documents. Quotes, sales orders and invoices are the records a seller gets asked about, and none of them is in the synchronization’s list. Deletions made in HubSpot do not reach vtenext either. Where head office is replacing vtenext rather than keeping it, the migration or integration guide is the better start. vtenext publishes its manuals in English as well as Italian, so none of this depends on reading Italian.

Six objects cover a first custom build. Accounts become HubSpot companies and contacts become contacts, both ways, keyed on the vtenext record id. vtenext writes each id as a module prefix and a record number, such as 3x310, and the whole string is the key, because the prefix is what tells one module’s record 310 from another’s.

Deals flow from HubSpot into vtenext as potentials, the record vtenext’s sales cycle starts from, carrying the HubSpot deal id, and vtenext’s id comes back onto the deal. From the potential, vtenext’s own chain runs: quote, sales order, invoice. Each of those comes into HubSpot one way, as a custom object associated to the deal or the company, and head office stays the only place they are edited.

Leads stay out of the first build. vtenext converts a lead into a contact, and optionally an account and a potential, once interest is confirmed, and HubSpot already holds the person before that point. We sync the contact that conversion creates rather than the lead.

The pattern is a webhook queue with a nightly check. vtenext’s REST webservice answers POST requests at /restapi/v1/vtews/ followed by the method name, authenticated with Basic credentials made of a user name and that user’s webservice access key. The documented methods cover create, update, retrieve, delete, query and describe, and vtenext’s SDK can register custom methods where a standard one falls short.

Events come from two places. A REST hook subscription, documented for vtenext’s Zapier set-up, posts to a URL when a record is created in a module or a process condition is met, and vtenext’s process engine can call an external web service client from a process step. Either one posts to our endpoint, which queues the event; a consumer retrieves the record and upserts HubSpot on the vtenext id, with associations in a second pass.

A nightly query compares counts per module, because we cannot assume vtenext retries a call that failed. Every record carries an auto-filled Modified Time, and the query method takes a WHERE clause, but the documentation shows no changed-since example, so we prove that filter against the client’s instance before relying on it.

What decides the route for vtenext is scope. If the modules its own synchronization covers are the whole requirement, configure that and stop. If quotes, orders or invoices have to reach HubSpot, one custom service over the REST webservice should own every object, including the ones the built-in synchronization could carry, because two mechanisms writing the same company record is how duplicates start.

A private Zapier integration, which vtenext documents step by step, suits a single flow at low volume, such as new leads raising a HubSpot task. It bills per task and keeps no keys of its own. There is no app in the HubSpot App Marketplace to weigh against either.

1. Scope. We confirm whether vtenext runs on premise or in its cloud, which version it is on, and whether its own synchronization covers the need.
2. Architect. One owner per object, the full vtenext id as the key, potentials as the only records HubSpot creates in vtenext, and the process steps that will call out.
3. Build. The service is written against a test installation of the client’s vtenext, with a dedicated integration user and a HubSpot sandbox portal.
4. Validate. We take one potential through quote, sales order and invoice in the test installation and check each lands on the right HubSpot deal.
5. Operate. We watch the queue and the nightly counts, and retest the hooks and process steps after each vtenext release.