Connect HubSpot with HeyGen

Overview

Integrating HubSpot with HeyGen represents a shift from static, template-driven communication to dynamic, AI-generated video personalization at scale. For enterprise technical teams, this integration is not merely about triggering a video; it is about building a robust, asynchronous state machine that bridges the gap between HubSpot’s CRM event stream and HeyGen’s compute-intensive video rendering engine.

The technical complexity of this integration lies in the asynchronous nature of video generation. Unlike standard REST operations that return a final resource immediately, HeyGen’s API initiates a rendering job that can take anywhere from seconds to several minutes. Consequently, the architecture must handle long-running processes, implement reliable callback mechanisms (webhooks), and ensure strict data consistency within HubSpot custom properties. This guide focuses on a production-grade implementation using HubSpot Private Apps and HeyGen’s v2 API, emphasizing idempotency, rate-limit resilience, and secure payload handling.

Core Prerequisites

Before initiating development, ensure the following technical requirements and permissions are met within both environments.

HubSpot Configuration

• Private App Access: Create a Private App in the target HubSpot portal. Do not use legacy API keys.
• OAuth Scopes: The integration requires crm.objects.contacts.read, crm.objects.contacts.write, and automation (if using Workflows to trigger webhooks). If you are generating videos based on Deal or Company data, include crm.objects.deals.read or crm.objects.companies.read.
• API Version: Use HubSpot CRM API v3 for all object operations.
• Custom Properties: Define a custom property group (e.g., Video_Automation) with fields for HeyGen_Video_URL (string), HeyGen_Render_Status (enumeration: PENDING, PROCESSING, COMPLETED, FAILED), and HeyGen_Job_ID (string).

HeyGen Configuration

• API Credentials: An Enterprise or Pro plan is required to access the v2 API. Obtain your X-Api-Key from the HeyGen settings dashboard.
• Template ID: Pre-configure a video template in the HeyGen UI. Note the template_id and the exact variable names (e.g., first_name, company_name) defined in the template.
• Webhook Secret: Configure a webhook endpoint in HeyGen to receive video.completed and video.failed events. Secure this with a signing secret to verify incoming payloads.

Infrastructure Requirements

• Middleware/Orchestrator: A serverless environment (AWS Lambda, Google Cloud Functions) or a dedicated Node.js/Python service to handle the logic between the two platforms.
• Persistence Layer: A lightweight database (Redis or DynamoDB) is recommended to track job_id mappings and prevent duplicate renders for the same CRM event.

Top Enterprise Use Cases

1. Hyper-Personalized Sales Outreach

Automate the generation of a personalized BDR introduction video when a Lead reaches a specific 'Qualified' status. By pulling the first_name and recent_conversion_event from HubSpot, the middleware can inject these into a HeyGen template, providing a high-touch experience without manual video production.

2. Automated Customer Onboarding

Upon a Deal being marked as 'Closed Won', trigger a video generation job that greets the new customer by name and mentions their specific package or industry. This video can then be automatically emailed via a HubSpot sequence once the render is complete.

3. Renewal and Retention Campaigns

For SaaS enterprises, use HubSpot's 'Contract End Date' to trigger a renewal reminder video 60 days prior to expiration. The video can dynamically reference usage statistics stored in HubSpot custom properties, creating a data-driven narrative that encourages retention.

Step-by-Step Implementation Guide

Step 1: HubSpot Workflow and Webhook Egress

Configure a HubSpot Workflow triggered by the desired CRM event (e.g., Property Value Changed). Use the "Send a Webhook" action.

Technical Detail: HubSpot webhooks sent from Workflows use a POST request with a JSON payload. Ensure your middleware validates the X-HubSpot-Signature-v3 header to prevent unauthorized requests. The payload will contain the objectId (Contact ID), which your middleware will use to fetch the latest CRM data.

// Example HubSpot Webhook Payload
{
  "objectId": 1234567,
  "propertyName": "lifecyclestage",
  "propertyValue": "marketingqualifiedlead",
  "changeSource": "WORKFLOW",
  "eventId": 101
}

Step 2: Data Enrichment and Validation

Upon receiving the objectId, the middleware must query the HubSpot CRM API v3 to retrieve the specific properties required for the HeyGen template.

Endpoint: GET /crm/v3/objects/contacts/{contactId}?properties=firstname,company,industry
Headers: Authorization: Bearer [YOUR_PRIVATE_APP_TOKEN]

Implement a validation layer here. If the firstname is missing or contains placeholder data (e.g., "N/A"), abort the process to avoid wasting HeyGen credits on low-quality renders.

Step 3: Initiating the HeyGen Render Job

Construct the request to HeyGen’s /v2/video/generate endpoint. You must map the HubSpot properties to the variables object defined in your HeyGen template.

Endpoint: POST https://api.heygen.com/v2/video/generate
Headers:

• X-Api-Key: [YOUR_HEYGEN_API_KEY]
• Content-Type: application/json

{
  "template_id": "tpl_3948572394",
  "title": "Onboarding Video for John Doe",
  "variables": {
    "first_name": {
      "name": "first_name",
      "type": "text",
      "properties": {
        "content": "John"
      }
    },
    "company_name": {
      "name": "company_name",
      "type": "text",
      "properties": {
        "content": "Acme Corp"
      }
    }
  },
  "test": false
}

Response Handling: HeyGen will return a 200 OK with a video_id. Store this video_id in your persistence layer mapped to the HubSpot objectId. Immediately update the HubSpot Contact record to set HeyGen_Render_Status to PENDING.

Step 4: Asynchronous Callback Handling

Do not poll the HeyGen API for status updates. Instead, use HeyGen Webhooks. Configure your listener to handle the video.completed event.

HeyGen Webhook Payload Example:

{
  "event_type": "video.completed",
  "event_data": {
    "video_id": "v_987654321",
    "url": "https://resource.heygen.com/video/xyz.mp4",
    "thumbnail_url": "https://resource.heygen.com/image/xyz.png"
  }
}

Verify the signature of the webhook. Once verified, use the video_id to look up the corresponding HubSpot objectId from your database.

Step 5: CRM Write-back and Finalization

Update the HubSpot Contact with the final video URL and set the status to COMPLETED. This update can then trigger a secondary HubSpot Workflow that sends the email to the customer.

Endpoint: PATCH /crm/v3/objects/contacts/{contactId}

{
  "properties": {
    "heygen_video_url": "https://resource.heygen.com/video/xyz.mp4",
    "heygen_render_status": "COMPLETED"
  }
}

Common Pitfalls & Troubleshooting

1. Rate Limiting and Concurrency

HubSpot enforces a limit of 100 requests per 10 seconds for standard Private Apps. If you are processing a bulk import of contacts that triggers hundreds of videos, your middleware must implement a queue (e.g., SQS or RabbitMQ) with an exponential backoff strategy.

HeyGen also has concurrent generation limits based on your plan. If you exceed these, the API will return a 429 Too Many Requests. Your integration must inspect the Retry-After header and delay subsequent requests accordingly. Implement a jitter algorithm to prevent "thundering herd" issues when retrying.

2. Idempotency and Credit Management

HeyGen renders cost credits. A common failure mode is a network timeout occurring after HeyGen has accepted the job but before the middleware receives the video_id. Without idempotency, a retry would trigger a second render, double-billing credits.

Mitigation: Generate a deterministic idempotency key based on the HubSpot objectId and the lastmodifieddate. Store this key in your database. Before calling HeyGen, check if a job with that key already exists.

3. Handling Render Failures

Video generation can fail due to invalid script content, template errors, or internal HeyGen issues. If you receive a video.failed webhook, you must update HubSpot with a FAILED status and log the error code. Common HeyGen error codes include:

• 4001: Invalid parameters (check your variable mapping).
• 4002: Credit insufficient.
• 5000: Internal server error (requires a retry after a delay).

4. Data Sync Latency

HubSpot's search index can have a slight lag. If your middleware queries a contact immediately after a webhook trigger, it might receive stale data. Always use the GET /crm/v3/objects/contacts/{contactId} endpoint for the most up-to-date values, as this bypasses the search index and reads directly from the primary datastore.

5. Webhook Security

Always validate the X-HubSpot-Signature-v3 for inbound HubSpot requests and the HeyGen signature for outbound callbacks. Failing to do so opens your middleware to SSRF (Server-Side Request Forgery) and unauthorized data injection into your CRM. Use a standard HMAC-SHA256 verification library to compare the signature in the header against a hash of the raw request body and your secret.