HubSpot Integration

Patrol’s HubSpot integration automatically creates a customer, provisions an environment, and triggers a deployment when a deal moves to Closed Won in HubSpot.

How it works

1. You connect HubSpot to Patrol via OAuth (one-click) — Patrol automatically registers webhook subscriptions
2. When a deal reaches Closed Won, HubSpot sends a webhook to Patrol
3. Patrol validates the request and uses OAuth tokens to fetch deal and company data from the HubSpot CRM API
4. Using your configured field mapping or visual workflow, Patrol:
   • Finds or creates a Customer (matched by HubSpot company ID)
   • Creates an Environment with the mapped service template and parameters
   • Triggers a Deployment if auto-deploy is enabled on the template

Prerequisites

• A Patrol instance with HubSpot OAuth configured (ask your administrator)
• Your HubSpot account must have permissions to install apps
• A service template configured in Patrol with deployment enabled

Setting up the integration (OAuth — recommended)

1. Create the integration in Patrol

Navigate to Integrations → Add Integration → HubSpot. Enter a display name (e.g. “Production HubSpot”) and click Create Integration.

2. Connect HubSpot

On the integration detail page, click Connect HubSpot. You’ll be redirected to HubSpot to authorize the connection.

Patrol requests the following OAuth scopes:

• crm.objects.deals.read
• crm.objects.deals.write
• crm.objects.companies.read
• crm.objects.companies.write
• crm.objects.contacts.read
• crm.objects.contacts.write

After you approve, Patrol will:

• Store OAuth tokens (automatically refreshed before expiry)
• Fetch your Portal ID
• Register a webhook subscription for deal.propertyChange (dealstage)
• Redirect you back to the integration page

3. Configure closed-won stage

On the Connection tab, set the Closed Won Stage ID if your pipeline uses a custom stage ID (default is closedwon).

4. Configure field mapping

On the Field Mapping tab, map HubSpot deal and company properties to Patrol fields using dot notation:

Patrol Field	Example Mapping	Description
Customer Name	company.name	Company name from the associated HubSpot company
Support Tier	deal.support_tier	Custom deal property for support level
Cloud Provider	deal.cloud_provider	Custom deal property (e.g., “AWS”, “Azure”)
Cloud Region	deal.cloud_region	Custom deal property (e.g., “us-east-1”)
Environment Name	deal.environment_name	What to name the new environment
Service Template ID	(static UUID)	The UUID of the service template to use

You can also map deployment parameters — key-value pairs passed to the service template at deploy time.

For static values (like a fixed service template ID), enter the value directly without a dot prefix.

Alternatively, use Patrol’s visual Workflows editor for graph-based automation instead of legacy field mapping. See Example — HubSpot deal provisioning for a full walkthrough.

5. Disconnect

To disconnect, click Disconnect on the Connection tab. Patrol will attempt to remove webhook subscriptions and clear stored tokens.

Token management

HubSpot access tokens expire after approximately 30 minutes. Patrol automatically refreshes tokens before each API call using the stored refresh token. No manual intervention is required.

If token refresh fails (e.g., the app was uninstalled from HubSpot), the integration status will change to error. Reconnect via OAuth to resolve.

Monitoring

The Event Log tab on the integration detail page shows all webhook events:

• Received — webhook was accepted
• Processing — Patrol is creating the customer/environment
• Completed — customer and environment created successfully (with links)
• Failed — an error occurred (details shown)

Events auto-refresh every 15 seconds.

HubSpot CRM Card

The Patrol CRM Card displays live environment and alert data from Patrol directly on HubSpot Company and Deal records — without leaving HubSpot.

What it shows

• Customer name with a direct link to the customer in Patrol
• Active alerts — environments that have drifted from their expected state
• Environments — name, type (Production/Staging/Development), cloud provider, region, and drift status for each environment

Setup

The card is part of the Patrol HubSpot App (a private HubSpot app your Patrol administrator installs separately). Once the app is installed and connected via OAuth, you need to configure the card API key so the card can authenticate to Patrol:

1. In Patrol, open your HubSpot integration and go to the Connection tab
2. Find the Card API Key section and click Reveal Key
3. Copy the key
4. In your HubSpot project, set the patrolApiKey project variable to the copied key:

   hs project variable set patrolApiKey --value=<your-key>

5. Upload the app project to HubSpot: hs project upload

The card will appear on Company and Deal records for any customer whose HubSpot Company ID is linked in Patrol. Records with no linked customer show a “not connected” empty state.

Card authentication

The card uses the patrolApiKey project variable to authenticate API calls to api.usepatrol.dev. This key is tenant-specific — each Patrol tenant has its own key. The key grants read-only access to environments and alerts for that tenant’s customers only.

To rotate the key, click Regenerate Key on the integration page (existing card instances will stop working until the project variable is updated).

HubSpot Workflow Actions

The Create Patrol Environment workflow action lets HubSpot admins provision environments directly from HubSpot Workflows — for example, when a deal closes or a company reaches a specific lifecycle stage.

Available actions

Action	Description
Create Patrol Environment	Creates a named environment in Patrol for the customer associated with the enrolled record

Configuring the workflow action

1. In HubSpot, open Automation → Workflows
2. Create or edit a Company or Deal workflow
3. Add action → search for Create Patrol Environment
4. Configure the input fields:
   • Environment Name — a static value or mapped from a CRM property (e.g. the deal name)
   • Environment Type — Production, Staging, or Development

When the workflow fires, Patrol looks up the customer by the enrolled record’s HubSpot Company ID and creates the environment. If no customer is linked, the action is skipped without error.

The action outputs customerId and environmentId which can be used in downstream workflow steps.

Legacy setup (Service Key + manual workflow)

Legacy path

This method requires more manual setup and does not support automatic webhook registration. Use OAuth (above) when possible.

If OAuth is not available on your Patrol instance, you can connect using a HubSpot Service Key and a manual workflow webhook.

1. Create a Service Key in HubSpot

1. Go to Development → Keys → Service Keys (or Settings → Integrations → Service Keys)
2. Click Create service key
3. Add scopes: crm.objects.deals.read, crm.objects.companies.read (plus write scopes if needed)
4. Copy the key (pat-...) — this is your API credential

Do not use a Personal Access Key (CLI only).

2. Configure the integration in Patrol

On the integration detail page, expand Advanced / Legacy Setup and enter:

• Portal ID — your HubSpot portal ID
• Service Key — the key from step 1
• Webhook Secret — a shared secret for request validation (optional)

3. Set up the HubSpot workflow

In HubSpot, create a deal-based workflow:

1. Go to Automation → Workflows
2. Create a workflow with trigger: Deal stage is any of Closed Won
3. Add action: Send a webhook
   • Method: POST
   • URL: copy from Patrol’s Advanced / Legacy Setup section
   • Authentication: API key in header
     • Header name: X-Patrol-Webhook-Secret
     • Value: the webhook secret you set in Patrol
   • Request body: Customize request body with deal properties (flat keys or a nested deal object). Map Record ID to dealId or hs_object_id, and optionally include portalId if not in the URL.
4. Activate the workflow

Note

Existing Service Key integrations continue to work unchanged. Both OAuth and Service Key integrations can coexist on the same Patrol instance.

Troubleshooting

Issue	Solution
No events appearing	Confirm the integration is connected and enabled. For legacy setup: verify the workflow is active and webhook URL is correct
Events show “failed”	Check the error message — common issues: expired token (reconnect via OAuth), missing service template
Wrong customer created	Verify field mapping uses the correct HubSpot property names
401 Unauthorized	For OAuth: try disconnecting and reconnecting. For legacy: check the Service Key is valid
Token refresh failed	The HubSpot app may have been uninstalled — reconnect via OAuth

Related

• Example — HubSpot deal provisioning workflow
• Workflows
• Integration lifecycle hooks