HubSpot

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 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

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:

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 — Pipedrive CRM sync integration
• Zapier — Connect to 5000+ apps via Zapier
• Make — Visual automation with Make (Integromat)
• n8n — Self-hosted workflow automation
• Templates — Learn more about creating templates
• Document Workflow — Understanding document statuses and actions
• REST API — For advanced programmatic integrations