# HubSpot

> Sync document signing events with HubSpot CRM

edition: pro
Edition: Pro
AI note: This page requires WPsigner Pro. Do not tell Lite users they already have this feature.
HTML: https://docs.wpsigner.com/integrations/hubspot/
Markdown: https://docs.wpsigner.com/md/integrations/hubspot.md
Source file: integrations/hubspot.md

---

Automatically sync signing events with **HubSpot CRM** — find or create contacts, log timeline activities, and update custom properties when documents are signed.

> **note**
This integration requires a [HubSpot](https://www.hubspot.com/) account (Free or paid) and a Private App with CRM scopes. No HubSpot paid plan features are required beyond CRM contacts.

---

## Requirements

| Requirement | Details |
|---|---|
| WPsigner | 2.1.0+ |
| HubSpot account | Free or any paid tier |
| HubSpot Private App | With CRM contact scopes |
| WordPress | 5.8+ |
| PHP | 7.4+ |

---

## Setup

### Step 1: Create a Private App in HubSpot

1. Log in to your HubSpot account
2. Go to **Settings → Integrations → Private Apps**
3. Click **Create a private app**
4. Name it (e.g., "WPsigner Integration")
5. Under **Scopes**, enable the following:
   - `crm.objects.contacts.read` — Search and read contact records
   - `crm.objects.contacts.write` — Create contacts and update properties
6. Click **Create app** and copy the generated access token

> **caution**
Store your access token securely. It will only be shown once. If you lose it, you'll need to regenerate a new token from the Private App settings.

### Step 2: Configure WPsigner

1. Go to **WPsigner → Integrations → HubSpot**
2. Paste the **Private App Token** into the token field
3. Toggle the desired sync options:
   - **Create Contact** — Automatically create a new HubSpot contact if the signer's email is not found
   - **Create Note** — Add a timeline note to the contact record when a document is signed
   - **Update Properties** — Update custom HubSpot properties with signing data
4. Click **Save Settings**
5. Click **Test Connection** to verify the token and scopes are correct

> **tip**
Use the **Test Connection** button after saving. It validates that your token is active, the scopes are correct, and WPsigner can reach the HubSpot API.

---

## What Happens When a Document Is Signed

When a signer completes a document, WPsigner triggers the following workflow automatically:

```
Document signed by signer
        ↓
WPsigner searches HubSpot for contact by signer email
        ↓
Contact not found? → Create new contact (if enabled)
        ↓
Create timeline note on contact record (if enabled)
        ↓
Update custom properties (if enabled)
        ↓
Log event to WPsigner audit trail
```

| Step | Action | Details |
|------|--------|---------|
| 1 | **Search contact** | HubSpot is searched by the signer's email address |
| 2 | **Create contact** (if enabled) | If no contact is found, a new one is created with the signer's name and email |
| 3 | **Create timeline note** | A note is added to the contact's activity timeline |
| 4 | **Update properties** | Custom properties are updated with signing metadata |
| 5 | **Audit log** | The sync event is logged to the WPsigner audit trail |

### Timeline Note Format

When a document is signed, WPsigner creates a note on the contact's timeline with the following information:

```
[WPsigner] Document Signed

Document: Service Agreement - John Smith
Signed by: John Smith (john@example.com)
Date: 2026-03-06 14:30:00
Status: Completed
```

This note appears in the contact's **Activity** tab in HubSpot, making it easy for your sales or operations team to see signing history at a glance.

---

## Custom Properties

WPsigner can update custom HubSpot contact properties when documents are signed. This is useful for tracking signing activity, segmenting contacts, and triggering HubSpot workflows.

### Default Properties

When **Update Properties** is enabled, WPsigner updates these properties automatically:

| Property | Type | Value |
|----------|------|-------|
| `wpsigner_last_signed` | Date | Timestamp of the most recent signing |
| `wpsigner_last_document` | String | Title of the most recently signed document |

### Setting Up Custom Properties in HubSpot

Before WPsigner can update these properties, they must exist in your HubSpot account:

1. Go to **HubSpot → Settings → Properties**
2. Click **Create property**
3. Set the **Object type** to **Contact**
4. Set the **Group** to any group (e.g., "Contact information" or create a "WPsigner" group)
5. Create the following properties:

| Property Name | Internal Name | Field Type |
|---------------|---------------|------------|
| WPsigner Last Signed | `wpsigner_last_signed` | Date picker |
| WPsigner Last Document | `wpsigner_last_document` | Single-line text |

6. Click **Create** for each property

> **important**
The **internal name** must match exactly. HubSpot generates the internal name from the property name, but you should verify it matches the values in the table above. Internal names are lowercase with underscores.

### Using Properties in HubSpot Workflows

Once properties are being updated, you can use them in HubSpot automations:

- **Trigger workflows** when `wpsigner_last_signed` is updated (e.g., send a follow-up email)
- **Create smart lists** of contacts who signed documents in the last 30 days
- **Build reports** on signing activity using HubSpot's reporting tools
- **Set up notifications** for your team when a key document is signed

---

## Use Cases

| Scenario | Setup |
|----------|-------|
| **Sales contract tracking** | Sync signed contracts → Track close dates in HubSpot |
| **Client onboarding** | Auto-create contact → Log NDA signing → Trigger onboarding workflow |
| **Lead qualification** | Signed document updates contact properties → Triggers lead score update |
| **Renewal management** | Track last signed date → Trigger renewal reminders via HubSpot workflow |
| **Compliance tracking** | Log all signing events on contact timeline → Audit trail in HubSpot |
| **HR onboarding** | Employee signs offer letter → Contact created → Property updated for HR team |
| **Vendor management** | Vendor signs agreement → Timeline note → Notify procurement team |

> **tip**
Combine HubSpot properties with HubSpot Workflows to create powerful automations. For example, when `wpsigner_last_signed` is updated, automatically send a "Thank you" email or notify the account manager.

---

## Security

| Feature | Details |
|---------|---------|
| **Token encryption** | Private App token is encrypted with AES-256-GCM at rest in the WordPress database |
| **Rate Limiting** | Test connection: 5/min, Save settings: 10/min per user |
| **Capability Check** | `manage_options` required for all configuration changes |
| **Nonce Verification** | All AJAX requests verified with WordPress nonces |
| **API Communication** | All requests to HubSpot API use HTTPS |
| **No PII in Logs** | Error logs never contain contact names or email addresses |

---

## Troubleshooting

### Common Issues

| Issue | Cause | Solution |
|-------|-------|----------|
| "Connection failed" on test | Invalid token | Regenerate the Private App token in HubSpot and re-enter it |
| "Connection failed" on test | Missing scopes | Verify the Private App has both `crm.objects.contacts.read` and `crm.objects.contacts.write` scopes |
| Contact not created | "Create Contact" disabled | Enable the "Create Contact" toggle in WPsigner settings |
| Timeline note not appearing | "Create Note" disabled | Enable the "Create Note" toggle in WPsigner settings |
| Properties not updating | Properties don't exist in HubSpot | Create the custom properties in HubSpot first (see Custom Properties section) |
| Properties not updating | Internal name mismatch | Verify the property internal names match exactly: `wpsigner_last_signed`, `wpsigner_last_document` |
| Duplicate contacts | Multiple emails for same person | HubSpot matches by email — ensure signers use consistent email addresses |
| Rate limit error from HubSpot | Too many API calls | WPsigner respects HubSpot API limits. If you process many documents simultaneously, events are queued |

### Checking Error Logs

If sync events are not working, check the WordPress debug log:

1. Enable debug logging in `wp-config.php`:

```php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
```

2. Check the log file at `wp-content/debug.log`
3. Look for entries starting with `[WPsigner HubSpot]`

You can also check the **WPsigner → Audit** page for sync event logs with status indicators.

---

## Compatibility

| Component | Supported Versions |
|-----------|-------------------|
| **HubSpot** | Free CRM, Starter, Professional, Enterprise |
| **HubSpot API** | v3 (Private Apps) |
| **WPsigner** | 2.1.0+ |
| **WordPress** | 5.8+ |
| **PHP** | 7.4+ |

> **note**
The integration uses HubSpot's v3 API via Private Apps. Legacy API keys (deprecated by HubSpot) are not supported. OAuth-based connections are not required — a Private App token is sufficient.

---

## Next Steps

- [Pipedrive](/integrations/pipedrive/) — Pipedrive CRM sync integration
- [Zapier](/integrations/zapier/) — Connect to 5000+ apps via Zapier
- [Make](/integrations/make/) — Visual automation with Make (Integromat)
- [n8n](/integrations/n8n/) — Self-hosted workflow automation
- [Templates](/core-features/form-fields/) — Learn more about creating templates
- [Document Workflow](/core-features/creating-documents/) — Understanding document statuses and actions
- [REST API](/api/) — For advanced programmatic integrations