Synthesia + HubSpot Integration Guide

Synthesia vs HeyGen: Which API Are You Actually Dealing With?

The two platforms look similar until you build with them. Synthesia is template-first and script-first. You design a video in the Synthesia editor, mark variable placeholders in the script, and the API renders personalized versions by swapping those variables at generation time. The avatar is presenter-style - it reads your script on camera.

HeyGen is avatar-first. The personalization model is more conversational and better suited to cold or warm outreach where you want a greeting, a pitch, and a name drop. For training modules, structured onboarding sequences, and product explainers sent to new customers - Synthesia’s model fits better.

Two practical differences that affect integration work. First, Synthesia has no native n8n node as of July 2026 - every call is a manual HTTP Request node. Second, video renders on Synthesia can run longer than HeyGen for the same length, because the rendering pipeline is optimized for quality over speed. Plan your polling intervals accordingly.

What You Need Before You Start

Four requirements before writing a line of configuration.

1. A Synthesia account on Creator plan or above. Starter plan does not include API access. Confirm under Settings - API Keys before you spend time on the integration.
2. A HubSpot account with Workflow permissions. You are setting up a Workflow that fires on a contact lifecycle stage change and posts to your middleware.
3. Middleware to receive the HubSpot webhook and call the Synthesia API. n8n (cloud or self-hosted) covers this guide. A custom Node.js or Python server works for production volume.
4. At least one Synthesia template with named variable placeholders in the script. Create it in the Synthesia editor before you build the integration - the template ID is what you will pass to the API.

Step 1: Set Up the HubSpot Trigger

The trigger is a HubSpot Workflow that fires when a contact lifecycle stage changes to “Customer.” You can adjust the enrollment condition to any stage that makes sense for your onboarding sequence - demo booked, contract sent, or first login are all reasonable.

1. In HubSpot, go to Automation - Workflows - Create Workflow - Contact-based.
2. Set the enrollment trigger: “Lifecycle stage is any of: Customer.”
3. Add a “Send a webhook” action. Method POST. Set the URL to your n8n webhook node URL.
4. In the webhook payload, include: contact_id, firstname, lastname, company, and any other fields your Synthesia template uses.

Do not rely on the webhook payload alone for contact data. HubSpot Workflow webhook payloads have field limits and can miss custom properties. Use the contact ID from the payload to fetch the full contact record from HubSpot’s API in the next step.

Step 2: Fetch the Template and Confirm Variable Slots

Before generating a video, confirm your template ID and the exact variable names it expects. A mismatch between your payload keys and the template’s variable names renders with the raw placeholder text visible in the output.

Add an HTTP Request node in n8n. Method GET, URL:

The response returns an array of templates. Each template object includes an id field and a data object containing the variable slots as keys. Note the exact key names - spelling and case must match your POST payload exactly.

In practice, you will run this call once to find your template ID and hardcode it. You do not need to call the templates endpoint on every video generation.

Step 3: POST /v1/videos - Create the Personalized Video

Add an HTTP Request node. Method POST, URL https://api.synthesia.io/v1/videos. Header: api-key: YOUR_KEY. Body type JSON.

The test: true flag generates a watermarked video that does not count against your plan minutes. Use it for all development and QA runs. The response returns an id field - this is the video ID you will use to check render status. Store it with a Set node.

One data hygiene step before this call: normalize the contact fields. Title-case the first name, trim whitespace, and handle empty fields explicitly. A missing company name in a template slot renders as a literal blank in the video.

Step 4: Poll for Render Status (or Register a Webhook)

Synthesia renders asynchronously. The POST /v1/videos call returns immediately with a video ID, but the actual render takes minutes - typically 2 to 8 minutes for a standard avatar video, longer for complex templates.

Polling approach (under 20 videos a day): Add a Wait node (120 seconds), then GET /v1/videos/{id}, then an IF node on the status field.

Cap your polling loop at 8 iterations (about 16 minutes total). If the video has not completed by then, route to an error branch and send a Slack alert. Do not poll indefinitely.

Webhook approach (above 20 videos a day): Register a webhook endpoint via POST /v1/videos/webhooks. Pass your endpoint URL and Synthesia will POST a payload when the video status changes. Your endpoint must return 200 in under 2 seconds - process the event async. Webhooks eliminate the polling loops and are the right architecture for anything running continuously.

When to Use Synthesia vs HeyGen for HubSpot

The short version: Synthesia for structured content delivered to customers, HeyGen for personalized outreach to prospects.

Use Synthesia when you need a polished, script-driven presenter video - a product walkthrough, a welcome-to-the-platform message, an L&D module sent after contract signing. The template system is purpose-built for this. The avatar is steady, professional, and reads exactly what you scripted.

Use HeyGen when you are sending outreach to cold or warm leads and the avatar needs to feel conversational. HeyGen’s personalization model handles name drops and dynamic phrasing better, has native MCP support, and has a verified n8n node. For high-volume sales prospecting, HeyGen is the faster build.

Some teams run both: HeyGen for the initial outreach sequence, Synthesia for onboarding videos after a deal closes. It works - just means maintaining two integrations. Only split if the use cases genuinely differ.

Error Handling You Should Not Skip

Three failure points account for most production incidents on Synthesia integrations.

1. Template variable mismatch. The most common cause of videos with placeholder text visible. Run a validation step before the POST call that checks every required variable key is present and non-empty in your payload. Alert on missing keys rather than rendering a broken video.
2. Rate limit on plan minutes. Synthesia’s API is rate-limited by plan. If you push volume against the Creator plan ceiling, requests return 429. Add retry logic with backoff. Log every 429 - they compound silently if your code ignores the response status.
3. Polling loop timeout. Render times vary. A polling loop with a hard cap that exits without alerting means a contact record with no video URL and no signal to anyone. If you exit the loop before completion, write a status marker to HubSpot and send a Slack alert so someone can manually trigger a re-render.