---

name: ops-hubspot-deal-stage-router
description: Use when mapping in-product user lifecycle events to HubSpot deal stages and triggering downstream CRM workflows. Translates key product milestones (signup, first draft, first matter file, 30-day active, upgrade, cancel) into HubSpot deal stage transitions and fires the corresponding sequences — AE assignment on SQL, onboarding email on Closed-Won, win-back campaign on Closed-Lost.
license: MIT
metadata:
id: ops.hubspot-deal-stage-router
category: ops
jurisdictions: [multi]
priority: P2
intent: [hubspot, ops, crm, deal-stage, lifecycle]
related: [ops-hubspot-property-mapper-stripe-sync, ops-churn-risk-detector, ops-nps-collector-in-chat]
source: Louis — HAQQ Legal AI (github.com/sboghossian/mini-claude-for-legal)
version: "1.0"

Ops — HubSpot Deal Stage Router

Purpose

The product generates events that directly map to sales pipeline stages. Without an automated bridge from product events to HubSpot, the CRM lags reality — AEs don't know a user is ready to close, CSMs miss churn signals, and win-back campaigns fire at the wrong time. This skill defines the canonical event → deal stage mapping and the workflows each transition triggers.

Event-to-stage mapping

Product event	HubSpot deal stage	Notes
User creates account	"Trial Start"	All new signups, including BYO-key users
First successful contract draft (draft saved or exported)	"Demo Complete"	Confirms the user has experienced the core value prop
First matter file uploaded to the workspace	"POC Active"	Signals intent to use for real work, not just exploration
Account has 30+ days active with ≥3 sessions/week	"Sales-Qualified Lead (SQL)"	Engagement threshold that signals genuine adoption
User upgrades from free/trial to any paid plan	"Closed-Won"	Also fires on first invoice paid, as fallback
User cancels subscription or downgrades to free	"Closed-Lost"	Also fires on chargeback or involuntary churn

Direction of travel: stages generally flow forward. A user who goes from Closed-Won back to Closed-Lost (cancels a paid subscription) creates a new deal record rather than updating the original — this preserves win history.

Workflow triggers per stage transition

SQL → AE Assignment

When a deal moves to "Sales-Qualified Lead":

• Assign the deal to the account executive (AE) based on the routing rules (geography, firm size, practice area specialization).
• Create a HubSpot task for the AE: "Reach out within 48 hours."
• Send AE a Slack notification: "New SQL: [Firm Name], [Usage stats], [Contact email]."

Closed-Won → Onboarding Sequence

When a deal moves to "Closed-Won":

• Enroll the contact in the onboarding email sequence (5-email sequence over 14 days).
• Assign a CSM (if Business/Enterprise tier).
• Create a HubSpot task for CSM: "Welcome call within 7 days."

Closed-Lost → Win-Back Sequence

When a deal moves to "Closed-Lost":

• Wait 90 days.
• Enroll the contact in the win-back sequence (3-email sequence over 14 days).
• Win-back emails should reference what the user accomplished during their time in the product, not generic reactivation copy.
• If the user re-engages (opens emails, clicks), escalate to AE for personal outreach.

Implementation

Each product event fires a webhook to the HubSpot API:

{
  "event": "first_contract_draft",
  "userId": "<HubSpot contact ID>",
  "timestamp": "<ISO 8601>",
  "metadata": {
    "documentType": "NDA",
    "jurisdiction": "UAE"
  }
}

A HubSpot workflow (or a middleware layer) receives the webhook and:

1. Finds or creates the HubSpot deal for the user.
2. Updates the deal stage to the mapped value.
3. Fires the appropriate workflow (email sequence, task creation, Slack notification).

Edge cases

• BYO-key users: they do not have a Stripe subscription. Their deal stages stop at "SQL" until they upgrade to a managed plan. Flag them in HubSpot with a byo_key: true property.
• Enterprise deals (negotiated contracts): deal stages are managed manually by the AE; product events are supplementary signals, not authoritative stage drivers.
• Team accounts: the deal is linked to the account admin (billing contact), not to individual team members. Individual user events bubble up to the account-level deal.
• Multiple products or tiers: if a firm has both a Pro individual and a Business team seat, they may have multiple deals. The router creates separate deals per subscription, not per contact.

Pair with

[[ops-hubspot-property-mapper-stripe-sync]] ensures that billing data (MRR, renewal date, plan name) is also reflected in HubSpot so AEs and CSMs have a complete picture.

Related skills

• [[ops-hubspot-property-mapper-stripe-sync]] — keeps billing properties in sync alongside stage transitions
• [[ops-churn-risk-detector]] — provides the churn signal that drives the Closed-Lost transition
• [[ops-nps-collector-in-chat]] — NPS promoters are strong signals for SQL and Closed-Won transitions