HubSpot + Pega integration

Pega is a platform for running work as cases. Pega Customer Service runs each service request as a case through the steps and rules the client defines, and Pega Sales Automation adds organizations, contacts, leads and opportunities on the same platform, with industry-specific data models. Everything is a case or a data object inside an application the client’s own Pega team builds and changes.

HubSpot comes in for the website, the forms, the email programs and the attribution that tell marketing which campaigns produce customers. The integration is asked to do two things: hand a contact who qualifies in HubSpot to Pega as a lead the sales process can pick up, and let marketing see what Pega did with it, from the opportunity it became to the service cases that followed.

What sets the pace is the Pega team rather than the API. Every event Pega sends out is a rule someone adds to a case flow, every data view it exposes is a data page someone configures for the API, and every change rides the client’s own release process from development through staging to production. Scoping starts with that team. If Pega is being replaced rather than joined, the migration or integration guide applies first.

Five objects cover a first build. Pega organizations become HubSpot companies and Pega contacts become contacts, keyed on their Pega IDs, with email used only for a contact’s first match. Contacts move both ways because both sides change them: Pega when a service agent updates a phone number, HubSpot when a person updates their details on a form. Pega Sales Automation models the organization and its accounts as separate objects, so the company key is the organization, never an account number.

Leads run the other way. A contact that qualifies in HubSpot opens a lead case in Pega through the API, carrying the HubSpot record id, and the case ID Pega returns is written back to the contact. From then on, Pega’s lead process owns the outcome.

Opportunities come into HubSpot one way as deals, so marketing can attribute pipeline without editing it. Service cases arrive as a read-only custom object for context, because a case worked in two systems has two owners. Activities, households and quotes wait for a second phase.

The pattern is a webhook queue, with Pega doing the calling. Pega’s documentation offers no webhook subscription for case changes, so the Pega team adds a Connect REST rule to each case flow in scope, referenced from an Integrator shape at the steps that matter, such as a lead converting or an opportunity closing. The call carries the case ID to our endpoint, which verifies it, queues it and acknowledges.

A consumer then reads the full case through the Pega API with an OAuth 2.0 client registered in Pega, maps it, and batch upserts into HubSpot on the Pega ID, with associations written in a separate pass. Leads flow back through the same client, created as new cases.

Reconciliation runs nightly against data views. The data API returns at most 5,000 results a page, and a data page sourced from a report definition times out after five seconds, so the Pega team exposes narrow, filtered data pages for the counts rather than one broad list.

For Pega, the decision is less about tools than about who does the Pega-side work. Every route needs the same changes inside Pega: a Connect REST rule in each case flow that should notify, a data page with API status for reconciliation, and an OAuth client registration. Once those exist, the only question is what receives the call.

A service we build receives it, reads the case, keys the record and reconciles every night. A general automation platform can receive it too, which suits a single case type at low volume, though it has nothing to replay from when a call goes missing. There is no marketplace app to weigh against either.

1. Scope. We meet the Pega team first, list the case types and flows in scope, and agree who adds each Connect REST rule and data page.
2. Architect. The event contract for each flow, Pega IDs as the keys, leads as the only records HubSpot creates in Pega, and the reconciliation queries.
3. Build. The service runs against the client’s Pega development environment and a HubSpot sandbox portal, with an OAuth client registered in each environment.
4. Validate. In staging, every notifying flow runs end to end, and counts from the data views are reconciled against HubSpot.
5. Operate. Pega-side changes ride the client’s release process, and we watch the queue, the dead letters and the nightly counts.