HubSpot + ServiceChannel integration

A facilities maintenance contractor does not choose ServiceChannel. Its customers do. A national retailer or grocer runs its estate on the platform, raises every repair there, and expects the provider to accept, check in, propose and invoice inside it. The contractor’s own operations live somewhere else entirely, which for many is an ageing in-house database that only two people understand.

That split produces a specific and expensive problem: nobody can see all the work in one queue. Work from one customer arrives by webhook into a platform account, work from another arrives by email, and work won directly arrives in a spreadsheet. Dispatchers reconcile by hand. A project manager watches a periodic work order in one tab and a subcontractor’s paperwork in another. Nothing in the business can answer how many open jobs exist tonight without someone counting.

The second reason is harder to see and costlier to ignore. A contractor that grows by winning a second platform-holding customer, or by acquiring a firm with its own provider account, ends up with two tenants on the same platform and no single view across them. Building the CRM as the one shared work queue, partitioned by brand, is the decision that makes that growth survivable. It has to be made before the first integration, because retrofitting tenant scope into a service that assumed one account is close to a rewrite.

Seven objects cover the shape. Work orders become deals, because a work order has a value, a status that progresses and an outcome. Locations become a custom site object rather than companies, since one customer can carry thousands of stores and a company record per store would drown the portal. Subscribers and providers both become companies, separated by a record type property.

Everything keys on the identifier ServiceChannel already assigned. The work order id is the anchor, and proposals, invoices and check-ins associate back to it. That matters more here than in most integrations because the contractor never creates the work order: the customer does, the id exists before your service hears about it, and any attempt to match on a description or an address will eventually merge two stores in the same plaza.

Invoices run the other way. The provider raises the invoice in HubSpot at a defined stage and the service posts it to ServiceChannel, one per work order, at or under the not-to-exceed amount agreed on the job.

The shape is a webhook queue with a polling backstop. ServiceChannel posts the event, the service verifies the Sign-Data header as an HMAC computed with SHA256 over the payload, returns a 2xx inside the five second budget and enqueues the work. Only then does a consumer fetch the full record, map it and upsert into HubSpot on the work order id.

Tenant scope is part of the envelope, not an afterthought. Every queued item carries the account it came from, and every write is checked against an allowlist of portal and tenant pairs that fails closed. Watermarks sit beside the link store so a sweep can re-read a window of work orders when an event never arrived, and every write is recorded in an append-only ledger. That ledger is what makes the invoice rule enforceable: an invoice already posted is never posted twice, however many times the event replays.

The deciding question is how many things must stay true at once, not how much volume there is. A work order has a status the customer owns, a not-to-exceed amount that caps the invoice, a proposal that may or may not be approved, and check-in records that prove a technician attended. Those constraints belong somewhere that can hold state.

A per-task automation platform holds none of it. It is a good way to prove the connection in a week, and a poor place to run a business that invoices from it. The second question is tenants: one provider account can be automated, two cannot, because tokens scope to the authenticating user and something has to decide which credential answers for which brand.

1. Scope. We list the tenants, the customers behind them and the events each one actually emits, because that catalogue varies by account and drives everything else.
2. Architect. The work order as the anchor object, the site model, the invoice rule and the tenant allowlist, written down before any code.
3. Build. Signature verification, queue, ledger and mapping against the sandbox, which refreshes weekly and is shared, so tests assume nothing persists.
4. Validate. A scripted run through create, accept, propose, check in and invoice, with counts reconciled against the platform.
5. Operate. Watch the dead letter queue, replay what failed, and re-verify the event catalogue whenever a new customer joins.