A generic welcome video is easy to ship and easy to ignore. New users can tell when a message was recorded once for everyone, and founders and customer success managers cannot record a personal welcome for every signup once volume picks up. Personalized onboarding videos close that gap: the same trusted face, speaking to each user by name about the thing they signed up to do.
This guide shows how to build it as an event-driven pipeline: what to personalize, how to trigger renders without slowing signup, how to handle webhooks safely, and how to keep the cost per user predictable.
What to personalize
Onboarding videos work when they are short and specific. Pull personalization from data you already collect at signup:
- First name and company, in the first sentence.
- The goal they picked in your signup survey ("I want to automate invoices"), mapped to one concrete first step.
- Their plan or trial length, if it changes what they should do first.
- The presenter: the founder for self-serve signups, or the assigned CSM for sales-led accounts.
Keep the script template to three or four sentences, roughly 30 to 45 seconds. Write one template per goal rather than letting an LLM improvise the whole message; it keeps tone consistent and makes review simple.
Architecture
The pipeline has four steps, and none of them should block the signup request:
- Signup event. Your app emits
user.signed_upto a queue. - Render job. A worker builds the script and calls
POST /generations. It stores the returned generation ID on the user record. - Webhook. PitchTwin calls your endpoint with
generation.succeededorgeneration.failed. You verify the signature, copy the MP4 to your storage, and mark the video ready. - Delivery. The video appears in the in-app welcome panel and in the second onboarding email.
Until the video is ready, show your generic welcome content. The personalized video replaces it when it arrives, so the user is never waiting on a render.
Step 2: the render job
const API = "https://pitchtwin.ai/api/v1";
// `db` below is your own data layer.
const firstSteps: Record<string, string> = {
invoices: "Connect your accounting tool first. It takes about two minutes.",
reporting: "Start with the weekly report template. It is already set up for you.",
};
export async function renderWelcome(user: {
id: string;
firstName: string;
company: string;
goal: keyof typeof firstSteps;
presenterAvatarId: string;
welcomeGenerationId?: string;
}) {
if (user.welcomeGenerationId) return; // already requested, do not duplicate
const res = await fetch(`${API}/generations`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PITCHTWIN_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
avatar_id: user.presenterAvatarId,
script: [
{ text: `Hi ${user.firstName}, welcome aboard.`, pause_after_ms: 400 },
{ text: `I saw you want to get ${user.company} set up for ${user.goal}.`, pause_after_ms: 300 },
{ text: firstSteps[user.goal], pause_after_ms: 300 },
{ text: "If anything is unclear, just reply to the welcome email. I read every one.", pause_after_ms: 0 },
],
voice: { speed: 1.0, language: "en" },
webhook_url: "https://app.example.com/hooks/pitchtwin",
}),
});
if (!res.ok) throw new Error(`PitchTwin ${res.status}`);
const gen = await res.json(); // { id, status: "queued" }
await db.users.update(user.id, { welcomeGenerationId: gen.id, welcomeStatus: "queued" });
}
Storing the generation ID before acknowledging the queue message makes the job safe to retry: if the worker crashes and the job runs again, it sees the ID and stops.
Only promise what is true in the last line. If nobody reads replies, change the sentence.
Step 3: verify the webhook
Every webhook carries a PitchTwin-Signature: t=<unix>,v1=<hex> header. v1 is the hex HMAC-SHA256 of ${t}.${raw_body} using the webhook secret from Dashboard → API keys. Verify against the raw body, before parsing JSON:
import crypto from "node:crypto";
export function verifyPitchTwin(rawBody: string, header: string, secret: string): boolean {
const parts = Object.fromEntries(
header.split(",").map((kv) => kv.split("=") as [string, string]),
);
const t = parts.t;
const v1 = parts.v1;
if (!t || !v1) return false;
// Reject old events to limit replays (5 minutes is a common tolerance).
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${t}.${rawBody}`)
.digest("hex");
const a = Buffer.from(expected, "hex");
const b = Buffer.from(v1, "hex");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
The full walkthrough, including Python, is in how to verify HMAC webhook signatures.
After verification, read type and data.id, look up the user by generation ID, and download data.video_url straight away. Video and audio links are signed and expire after 24 hours, so your stored copy is what the email and the in-app panel should point to.
Handle the edges
- Missed webhooks. Webhooks are delivered once. Run a reconciliation job every few minutes that polls
GET /generations/:idfor users still markedqueuedafter a while. - Failures. On
generation.failed, keep showing the generic video. Failed generations are refunded in full automatically, so one retry is cheap: you only pay for a render that succeeds. - Odd input. Users type company names in all caps, with emoji, or as URLs. Clean the fields before they reach the script, and fall back to a version without the company name if the value looks wrong.
Who should present
The presenter's face is the reason this works, so it has to look like them. PitchTwin builds each avatar from a real video of the person and keeps that footage, so the welcome looks 1:1 like your founder or CSM, with their own expressions and lighting rather than a smooth re-generated face. Each avatar is pinned to its engine version, so the presenter looks the same in a welcome sent today and one sent next spring.
For sales-led accounts, create one avatar per CSM and pick the presenter from the account owner field. Each presenter must agree to their avatar being used; PitchTwin's Terms require it, and your product should record that agreement.
Keeping cost per user predictable
PitchTwin charges prepaid tokens that never expire, with no seats or subscription: 1.5 tokens per second when PitchTwin voices the script, 1 token per second with your own audio. A 40-second welcome voiced by PitchTwin is 60 tokens.
| Monthly signups | Tokens per month | Packs | Cost |
|---|---|---|---|
| 200 | 12,000 | 1 × Scale | $149 |
| 1,000 | 60,000 | 5 × Scale | $745 |
That is about $0.75 per user at Scale pricing. Two ways to bring it down: render only for signups that complete a qualifying step (verified email, first project created), and keep the script tight, since cost scales with seconds. If you already generate speech elsewhere, audio mode is the lower rate. Full numbers are on the pricing page.
White-label by default
The welcome should feel like it came from your product. PitchTwin output carries no watermark and no PitchTwin branding, and videos are delivered to your webhook, so users only ever see your brand. The personalized video API page covers the wider workflow.
Try it
Record a 30-second clip, create an avatar in the dashboard, and generate a test welcome in the Playground; it shows the equivalent cURL and Node request. Sign up for 60 free seconds with no card, then follow the webhooks docs to wire it into your signup flow.