HeyGen + Pipedrive Integration: Step-by-Step Guide
By Umar Asghar, AI Integration Engineer - July 13, 2026
TL;DR
You will set up a Pipedrive webhook that fires when a deal moves to a target stage, pull the person name, org name, and deal title, call HeyGen to render a personalized video, wait for the render, and write the video URL back as a note on the Pipedrive deal. The whole chain runs server-side with no no-code tools. Estimated build time: 2 to 3 hours including test renders.
What You Need Before You Start
Four things: a Pipedrive account on the Professional plan or above (webhooks require it), a HeyGen account on Creator or above with API access enabled, a server or serverless function to receive webhooks and make API calls, and a HeyGen video template with named variables already set up in the dashboard.
Before writing any code, open your HeyGen template and note every variable name exactly as it appears. A mismatch between the template variable and your API payload produces a render with a blank field, not an error - so you will only catch it on review.
Step 1: Create the Pipedrive Webhook
Pipedrive webhooks are registered via API. POST to /v1/webhooks with your API token as a query parameter:
POST https://api.pipedrive.com/v1/webhooks?api_token=YOUR_TOKEN
{
“subscription_url”: “https://your-server.com/webhook/pipedrive”,
“event_action”: “updated”,
“event_object”: “deal”
}
Pipedrive will POST every deal update to your URL, including the full current and previous objects. You filter to your target stage inside the receiver. If you need to verify the webhook is only from Pipedrive, pass a secret in the URL path or a custom header and validate it on your server.
To list your stage IDs so you know which one to filter on:
Step 2: Build the Webhook Receiver
Your receiver needs to do three things: validate the payload is a deal update to the right stage, extract the personalization data, and return a 200 immediately before doing any async work. Pipedrive expects a fast acknowledgment - do not block the response on the HeyGen call.
// Express example (Node.js)
app.post(‘/webhook/pipedrive’, async (req, res) => {
const { current, previous } = req.body;
// Only act on the target stage
if (current.stage_id !== TARGET_STAGE_ID) {
return res.sendStatus(200);
}
// Skip if stage did not change
if (previous.stage_id === current.stage_id) {
return res.sendStatus(200);
}
res.sendStatus(200); // acknowledge first
await enqueueRender(current); // async work after
});
Extract three fields from current: the person name (person_name), org name (org_name), and deal title (title). The deal ID (id) is also required for the note write-back later. If any personalization field is null, route that deal to a fallback - a blank variable in a video is worse than no video.
Step 3: Call the HeyGen Render Endpoint
POST to https://api.heygen.com/v2/video/generate with your API key in the X-Api-Key header. The body maps your Pipedrive fields to HeyGen template variables:
{
“video_inputs”: [{
“character”: {
“type”: “avatar”,
“avatar_id”: “YOUR_AVATAR_ID”,
“avatar_style”: “normal”
},
“voice”: {
“type”: “text”,
“input_text”: “Hi {{first_name}}, congrats on moving to {{deal_title}}. We are excited to work with {{org_name}}.”},
“voice_id”: “YOUR_VOICE_ID”
}
}],
“variables”: {
“first_name”: { “name”: “first_name”, “type”: “text”, “properties”: { “content”: personName } },
“deal_title”: { “name”: “deal_title”, “type”: “text”, “properties”: { “content”: dealTitle } },
“org_name”: { “name”: “org_name”, “type”: “text”, “properties”: { “content”: orgName } }
},
“dimension”: { “width”: 1280, “height”: 720 },
“test”: true
}
The response body contains data.video_id. Store this along with the Pipedrive deal_id - you need both for the next step. Set test: true until you have verified the output on two or three real deals. Test renders are watermarked but free.
Step 4: Poll for Render Completion
HeyGen renders asynchronously. A standard avatar video takes 1 to 5 minutes. The simplest approach under 20 videos a day is polling:
GET https://api.heygen.com/v1/video_status.get?video_id=VIDEO_ID
Header: X-Api-Key: YOUR_KEY
// Response when complete:
{
“data”: {
“status”: “completed”,
“video_url”: “https://files.heygen.ai/…”,
“duration”: 18.4
}
}
Poll every 30 seconds, cap at 15 attempts (7.5 minutes total). If status is still processing after that, route to your error handler. If status is failed, do not retry the same payload without investigating - HeyGen failed renders usually point to a bad avatar ID or a voice ID that has been removed.
For higher volume, register a HeyGen webhook instead of polling: POST to /v1/webhook/endpoint.add with your callback URL and subscribe to avatar_video.success and avatar_video.fail. HeyGen will POST the completed video URL directly to you.
Step 5: Write the Video Link Back to Pipedrive
Once you have the video URL, create a note on the deal using POST /v1/notes:
POST https://api.pipedrive.com/v1/notes?api_token=YOUR_TOKEN
{
“deal_id”: 12345,
“content”: “Personalized video ready: https://files.heygen.ai/...\n\nRendered on 2026-07-13. Link expires in 7 days.”,
“pinned_to_deal_flag”: true
}
Setting pinned_to_deal_flag: true keeps the note at the top of the deal card so reps do not have to hunt for it. Include the render date in the note body - HeyGen URLs expire after 7 days and reps need to know when to stop trusting a link. If you need permanent URLs, download the video after rendering and serve it from your own storage.
Error Handling: Three Cases That Will Break This in Production
These are not edge cases. Every production integration hits all three within the first month.
HeyGen rate limits (429)
The API returns 429 when you exceed the render concurrency limit for your plan. Add exponential backoff: wait 5 seconds on first 429, 10 on second, 20 on third, then alert and drop to a dead-letter queue rather than retrying indefinitely.
Avatar or voice ID no longer valid
If someone deletes or renames an avatar in the HeyGen dashboard, every subsequent render fails. This is not retryable. Catch the error, alert your team immediately, and halt the queue until the ID is corrected. Verify your avatar ID with GET /v2/avatars on deploy and on any HeyGen plan change.
Pipedrive note write fails after video is ready
If the Pipedrive API call fails after the render completes, you have a video URL with no destination. Store the video URL and deal ID to a persistent log before the Pipedrive write. If the write fails, retry it - unlike re-rendering, writing a note is idempotent and cheap.
Building This for a Sales Team? Start with a Pipeline Audit
The Pipedrive integration above handles one stage and one template. Production deployments usually need multi-stage routing, fallback templates, and delivery tracking. The Pipeline Audit maps your current CRM setup to an architecture that covers all three. 30 minutes, no commitment.
Get your Pipeline Audit
FAQ
Which Pipedrive plan do I need for webhooks?
Pipedrive webhooks are available on Professional and above. The Essential and Advanced plans do not expose the webhook API. If you are on a lower plan, you can poll the Pipedrive Deals API on a schedule instead, but you will trade real-time triggers for a polling lag.
Can I filter to a specific pipeline or stage instead of all deal updates?
Yes. Register the webhook with event_action: updated and event_object: deal, then in your receiver check current.stage_id against the stage ID you want. You can find stage IDs via GET /v1/stages. Filtering in the receiver is simpler than maintaining multiple webhooks.
HeyGen video URLs expire after 7 days - what should I do?
For same-day outreach the direct URL is fine. For anything logged in Pipedrive as a reference, download the MP4 using the URL, re-host it on S3 or similar, and write the permanent URL to the note instead. HeyGen's CDN URL is a delivery mechanism, not archival storage.
How do I handle duplicate renders if the deal stage flips back and forward?
Track renders by deal_id in a small database table or key-value store. When a webhook arrives, check whether a render already exists for that deal in the target stage. If it does, skip the HeyGen call and optionally write a note saying the existing video link is still valid.
ABOUT THE AUTHOR
Umar Asghar is the CTO of Kastiv. He builds production AI video and API integration pipelines.