HeyGen + Salesforce Integration Guide 2026

Before You Pick an Approach

You need: a Salesforce org on Enterprise Edition or above, a HeyGen account with API access (paid plan), a webhook receiver you control (a small Node/Python server or a hosted function - covered in Step 3), and a custom field on the Opportunity object. Create that field now: type URL, API name Personalized_Video_URL__c, label “Personalized Video URL”. Everything else follows.

One constraint to plan around before writing a single line: Salesforce does not allow synchronous HTTP callouts from trigger context. Every callout must be async. This is not a workaround - it is the architecture.

Approach 1: Record-Triggered Flow with HTTP Callout Action

Use this path if you do not have a Salesforce developer, want to avoid deployments, or need to ship inside a week. Flow’s HTTP Callout Action (available Summer ’23 and later) lets you define an external service call in the Flow Builder UI and invoke it as a step - no Apex required.

Note: Process Builder is deprecated. Do not use it. Any existing Process Builder automation should be migrated to Flow before adding new logic.

1. In Setup, open Flows and create a new Record-Triggered Flow on the Opportunity object.
2. Trigger condition: Record is updated. Entry condition: StageName equals your target stage (e.g., “Proposal/Price Quote”) AND the prior value was different. This prevents re-fires on unrelated field updates.
3. Run the flow: After the record is saved, in a new system context. This automatically makes the callout async - you cannot call an HTTP action from a before-save flow.
4. Add an Action element, type HTTP Callout. Define the external service (your webhook URL, POST method, JSON body). Map these fields from the triggering record into the payload: {!$Record.Id}, {!$Record.Name}, {!$Record.Account.Name}, {!$Record.StageName}, and the associated Contact’s first name via a Get Records element.

Approach 2: Apex Trigger with @future Callout

Use this path if you need bulk-safe handling, want to conditionally fire based on field logic that Flow cannot express cleanly, or your org already has developer capacity. The pattern: a thin trigger hands off to a handler class, which queues an async method.

Store your webhook URL in Setup > Named Credentials as HeyGen_Webhook. This keeps the URL out of code and handles authentication headers cleanly. Never hardcode an endpoint URL in Apex.

Step 3: The Webhook Receiver

Your webhook receiver is a small HTTP server that accepts the Salesforce payload and drives the HeyGen render. Validate the incoming request with a shared secret header before processing anything - Salesforce callouts do not have a built-in signature scheme, so a secret token in a custom header is the standard pattern.

Respond 200 immediately and run the render async. Salesforce callouts have a 120-second timeout. A HeyGen render takes 1 to 5 minutes, so if you await the render inside the request handler, every callout will time out and log an error in Salesforce.

Step 4: Trigger the HeyGen Render and Poll for Completion

From your webhook receiver, POST to HeyGen’s generate endpoint with the Salesforce field values mapped to your template variables. Include test: true in every payload until you are ready to go live - test renders are watermarked but cost zero credits.

The response returns a video_id inside data. Store it alongside the opportunity_id, then poll GET /v1/video_status.get?video_id={video_id} every 30 seconds until data.status is completed or failed. Cap retries at 15 (7.5 minutes). If status is still processing after the cap, log the opportunity_id and alert - do not retry blindly.

At higher volumes, register a HeyGen webhook instead of polling: POST /v1/webhook/endpoint.add with event types avatar_video.success and avatar_video.fail. HeyGen POSTs the completed video URL directly to your endpoint, eliminating polling loops entirely.

Step 5: Write the Video URL Back to Salesforce

Once the render completes, data.video_url has the hosted URL. Write it to the Opportunity using the Salesforce REST API. You will need a connected app with OAuth 2.0 credentials - or a named credential if you are calling back from a server you control.

A successful PATCH returns HTTP 204 with no body. Log any non-204 response with the opportunity ID - a 404 means the record was deleted between trigger and write-back, a 401 means your access token expired. Use a refresh token flow or a long-lived JWT bearer grant to avoid token expiry issues in production.

One caveat on the video URL: HeyGen’s hosted URLs expire after 7 days. For same-day outreach the direct URL is fine. If your sales cycle is longer or you need the URL to remain valid in Salesforce indefinitely, download the video and re-host it to S3 or Cloudinary before writing the URL back.

Salesforce-Specific Error Handling

Three governor limit scenarios that differ from a standard webhook integration:

Testing: Sandbox First

Never build this in production. The testing sequence:

1. Deploy to a Full or Partial Copy Sandbox. Create a test Opportunity and manually move the stage. Confirm the trigger fires and the payload arrives at your receiver (check your server logs first, not Salesforce debug logs).
2. With test: true in the HeyGen payload, confirm a watermarked render completes and the video URL appears in Personalized_Video_URL__c on the Sandbox Opportunity.
3. Run a bulk test: import 10 Opportunities via Data Loader with the target stage. Confirm all 10 trigger without hitting governor limits. Check the async job queue in Setup > Apex Jobs.
4. Remove test: true only in production, after the Sandbox run passes.

For Apex unit tests: mock the HTTP callout with a class that implements HttpCalloutMock. Salesforce requires 75% code coverage to deploy, and live callouts are not permitted in test context - mocking is mandatory, not optional.