HubSpot + Dolibarr integration

Dolibarr is the open-source ERP and CRM that a freelancer, an association or a small company installs because it is free software that covers the job. It runs on the company’s own server or with a SaaS host, it handles proposals, sales orders, invoices and stock, and it keeps customers and prospects in one third party list. When the business adds HubSpot for marketing and a sales pipeline, the two start to disagree about who the customer is and what they have bought.

The ask is usually modest and specific. Sellers want to see whether a proposal was signed and whether the invoice behind it was paid, without logging in to the ERP. Marketing wants prospects entered in Dolibarr to reach HubSpot as contacts. Finance wants a deal marked won in HubSpot to turn into something it can bill, rather than an email asking someone to type it in again.

Dolibarr makes this more approachable than most ERPs. The REST API ships with it as a module, and so does a Webhook module that posts a JSON message when a business event fires. What it does not offer is a change timestamp that its own developers recommend relying on, and that gap shapes the design more than anything else on this page.

Six objects cover what sellers and finance ask about. Third parties that are customers or prospects become HubSpot companies, and their contacts become HubSpot contacts. Commercial proposals become deals, because the proposal is the Dolibarr record that is signed or refused once. Sales orders and customer invoices land on custom objects associated to the deal and the company, and products and services become HubSpot products.

The third party list needs filtering on the way in. Dolibarr keeps customers, prospects and suppliers as third parties with different statuses, and the API’s list call takes a mode that asks for customers rather than suppliers. Loading the list unfiltered puts suppliers into a sales pipeline. Proposals carry their outcome in their own trigger codes, PROPAL_CLOSE_SIGNED and PROPAL_CLOSE_REFUSED, which is what closes the deal as won or lost.

Every record keys on its Dolibarr id, held in a custom HubSpot property. Names and customer codes are for people; the id is for the sync. Contacts key on email, with the Dolibarr contact id as the tie breaker. Everything moves into HubSpot except one write back: a closed won deal creating the third party and, where finance wants it, a draft order.

The shape is a webhook queue with a sweep behind it. The Webhook module posts a JSON message to our ingest endpoint for each trigger code we register, with third party, contact, proposal, order and invoice events among them. The endpoint acknowledges at once and queues the message. A consumer then reads the full record over the REST API with the integration user’s key, because the event is a prompt rather than a copy we trust, and upserts into HubSpot in batches keyed on the Dolibarr id, followed by an association pass.

The sweep exists because of what the documentation leaves out. Dolibarr’s wiki describes no retries for webhook messages, and its own development rules say not to rely on the modification stamp. So each night the sweep pages through every tracked list, compares ids and statuses with HubSpot and replays the difference. Where the multicompany module is on, every call names its entity and every stored key carries it.

The deciding question is whether anything has to survive a missed event. A notification, such as posting a signed proposal into a sales channel, can ride on an iPaaS catching the Webhook module’s JSON, and it is a fair way to prove the value. A pipeline someone forecasts from needs the sweep, the keys and the replay, and that is a service with somewhere to keep state.

Hosting is the other question. On a self-hosted server, whoever runs it has to enable the REST API and Webhook modules and allow the calls in and out, and those are settings rather than code. With a SaaS host, we confirm before scoping that both modules are available on that host’s plan.

1. Scope. We find out where Dolibarr runs, which version and modules are enabled, whether multicompany is on, and which events matter to sellers and finance.
2. Architect. We fix the trigger codes, the Dolibarr id keys, the third party filter, the queue and the nightly sweep, and write them down.
3. Build. Ingest, queue, consumer and sweep are written against a test instance and a HubSpot sandbox, with a dedicated API user and a portal allowlist.
4. Validate. We backfill each object, reconcile counts by type against Dolibarr’s lists, and replay a day of events twice to prove nothing duplicates.
5. Operate. We watch the queue and the sweep, replace the API key on a schedule, and retest after each Dolibarr upgrade.