DEV Community: Syncoders

Building an AI Shorts pipeline with ffmpeg: 9:16, Ken Burns zoom, captions that match the voice

Syncoders — Mon, 26 Oct 2026 12:53:35 +0000

TL;DR

Ask an LLM for a scene plan in JSON, and check every field before you use it.
Crop each image to 9:16 first, then add a slow zoom with ffmpeg's zoompan filter.
Make each scene as long as its voice-over (measured with ffprobe), not as long as the LLM guessed.
Split the narration into short caption chunks, time them by length, and burn them into the video.
Encode every scene the same way, then join them with no re-encoding.
Retry rate limits and server errors. Fail fast on bad requests and bad keys.

Calling an image API and a text-to-speech API is the easy part of an "AI video generator". Turning their output into a video people will actually watch is the work. This post builds that pipeline with Node and plain ffmpeg. Each step is one ffmpeg command you can paste into a terminal first, then wrap in code.

A few words first

LLM: a large language model, the kind of AI that writes text (and JSON).
TTS (text-to-speech): a service or program that turns text into a voice recording.
ffmpeg / ffprobe: free command-line tools. ffmpeg converts and edits video and audio. ffprobe reads facts about a file, such as its length.
16:9 and 9:16: width-to-height ratios. 16:9 is a landscape YouTube video. 9:16 is a vertical Short, Reel or TikTok.
Filter: an ffmpeg step that changes the picture or sound, like scale (resize) or crop.

The whole pipeline

One brief, like "3 tips for better sleep", goes in. The LLM breaks it into scenes. Each scene gets an image and a voice-over. ffmpeg turns each scene into a short clip, then joins the clips into one MP4.

Step 1: get a scene plan you can trust

What goes wrong: the LLM's answer crashes your code, or produces a video that's far too long.

Everyday example: you ask for 6 scenes in JSON. The model wraps the JSON in a code fence, adds "Here's your plan!" before it, returns 14 scenes, and writes "durationSec": "3s" as text instead of a number.

Why it happens. An LLM predicts likely text. It usually follows your format, but nothing forces it to.

The fix: ask for JSON, then check every field before you use it. On OpenAI-compatible APIs, response_format: { type: "json_object" } asks the model for JSON only. The plan looks like this:

{
  "title": "3 tips for better sleep",
  "scenes": [
    { "imagePrompt": "dim bedroom, warm lamp, cinematic", "narration": "Keep the same wake-up time, even on weekends.", "durationSec": 3 },
    { "imagePrompt": "phone face down on a nightstand", "narration": "Put screens away thirty minutes before bed.", "durationSec": 3 }
  ]
}

Then, in your code:

Strip any code fences and text around the JSON.
JSON.parse it.
Check every field has the right type.
Clamp the numbers: for example 2 to 12 seconds per scene, and a maximum scene count.
If anything is still wrong, throw an error your job queue will retry.

Step 2: turn a still image into a moving 9:16 clip

What goes wrong: the Short looks stretched, or looks frozen.

Everyday example: your image API returns a 16:9 landscape picture. You resize it to 720×1280, and the round sun becomes a tall oval. Or you keep it sharp and still, and viewers swipe away because nothing moves.

Why it happens. Resizing a landscape image to a portrait size stretches it, because the shapes don't match. The right move is to crop: keep a 9:16 slice from the middle and drop the sides.

For motion, the cheapest effect that looks deliberate is the Ken Burns effect: a slow zoom into a still photo. It's named after the documentary maker who used it heavily. ffmpeg's zoompan filter does it. Each frame shows a slightly smaller, centred part of the image, stretched to fill the screen, so the picture slowly pushes in.

The fix: scale up, crop to 9:16, then zoom. Here's the whole command for one scene:

W=720; H=1280; FPS=25; DUR=3.4
FRAMES=85   # DUR × FPS

ffmpeg -y -loop 1 -i scene.png -i voice.mp3 -filter_complex "\
[0:v]scale=900:1600:force_original_aspect_ratio=increase,crop=900:1600,\
zoompan=z='min(zoom+0.0008,1.15)':x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':d=$FRAMES:s=${W}x${H}:fps=$FPS,\
format=yuv420p[v]" \
  -map "[v]" -map 1:a -af apad -t $DUR \
  -c:v libx264 -preset veryfast -c:a aac -ar 44100 -ac 2 segment.mp4

What each part does:

-loop 1 -i scene.png repeats the still image as a video stream. -i voice.mp3 adds the voice-over.
scale=900:1600:force_original_aspect_ratio=increase,crop=900:1600 grows the image until it covers 900×1600, then cuts away what sticks out. That gives a 9:16 picture whatever shape the source was. It's 1.25× bigger than the output on purpose: zoompan jitters when it zooms into a small image.
z='min(zoom+0.0008,1.15)' zooms in 0.08% per frame, which is 2% per second at 25 fps, and stops at 15%. The x and y parts keep the zoom centred.
d=$FRAMES:s=${W}x${H}:fps=$FPS sets the clip's frame count, output size and frame rate.
format=yuv420p uses the pixel format phones and browsers can play.
-af apad pads the voice with silence, and -t $DUR cuts the clip to the exact length.

For 16:9, swap the numbers: 1600:900 and s=1280x720.

Step 3: make each scene as long as its voice

What goes wrong: the narration gets cut off mid-word at the end of a scene.

Everyday example: the LLM planned 3 seconds for "Keep the same wake-up time, even on weekends." The voice takes 3.11 seconds to say it, so "weekends" gets clipped.

Why it happens. The LLM has no idea how fast your TTS voice speaks. Its durationSec is a guess.

The fix: generate the voice first, measure it with ffprobe, then set the scene length:

ffprobe -v error -show_entries format=duration -of csv=p=0 voice.mp3
# 3.108571

const speech = await probeDuration(audioPath);            // runs the ffprobe command above
const dur = Math.max(scene.durationSec, speech + 0.25);   // never shorter than the voice, plus a breath

That one line is the difference between a clip that sounds edited and one that sounds broken.

Step 4: burn in captions that follow the voice

What goes wrong: viewers with the sound off don't know what the video says.

Everyday example: someone scrolls past your Short on a train, with their phone on mute. There's no text on screen, so they never hear your three tips.

Why it happens. Many people watch Shorts on mute, and a voice-over alone tells them nothing.

The fix: split the narration into chunks of 3 or 4 words, give each chunk a start and end time, and draw them onto the video. The timed chunks are saved as an SRT file, a plain-text subtitle format. ffmpeg's subtitles filter draws ("burns") them into the picture. It uses libass, a subtitle library that standard ffmpeg builds include.

Most TTS services don't tell you when each word is spoken. Giving each chunk time in proportion to its length is close enough to read along:

function captionCues(text: string, duration: number, maxWords = 4) {
  const words = text.trim().split(/\s+/);
  const chunks: string[] = [];
  for (let i = 0; i < words.length; ) {
    let n = Math.min(maxWords, words.length - i);
    for (let k = 0; k < n - 1; k++) if (/[.,!?;:]$/.test(words[i + k])) { n = k + 1; break; } // break at punctuation
    chunks.push(words.slice(i, i + n).join(" "));
    i += n;
  }
  const total = chunks.reduce((s, c) => s + c.length + 2, 0);
  let t = 0;
  return chunks.map((c) => { const d = (duration * (c.length + 2)) / total; const cue = { start: t, end: t + d, text: c }; t += d; return cue; });
}

const ts = (s: number) => new Date(s * 1000).toISOString().slice(11, 23).replace(".", ",");
const toSrt = (cues: { start: number; end: number; text: string }[]) =>
  cues.map((c, i) => `${i + 1}\n${ts(c.start)} --> ${ts(c.end)}\n${c.text}\n`).join("\n");

For the example line, this writes:

1
00:00:00,000 --> 00:00:01,576
Keep the same wake-up

2
00:00:01,576 --> 00:00:02,056
time,

3
00:00:02,056 --> 00:00:03,358
even on weekends.

Then add the subtitles filter to the Step 2 command, just before format=yuv420p:

,subtitles=scene-0.srt:force_style='FontName=DejaVu Sans,FontSize=10,Bold=1,Outline=1.6,Shadow=0.8,Alignment=2,MarginV=64'

Two things that cost me time:

FontSize is not in pixels. For SRT files, libass lays text out on a canvas 288 units tall, then scales it to the video. So FontSize=10 on a 1280-pixel-tall video is about 44 px. For text about 6% of the short side, use FontSize = 0.06 × min(W, H) × 288 / H.
File paths inside a filter string are painful. Colons, backslashes and quotes all need escaping, and Windows drive letters make it worse. Run ffmpeg from the folder that holds the SRT and pass just the file name. Never put user text directly into a filter string; write it to a file first.

Step 5: a free voice for drafts

What goes wrong: every test render costs money.

Everyday example: you're tuning caption sizes and render the same video 30 times. With a paid voice API, you pay for the same three sentences 30 times.

Why it happens. Paid TTS bills per character, even for drafts nobody will see.

The fix: use an offline voice for drafts. If your ffmpeg build includes flite (a small offline speech engine), ffmpeg can speak on its own:

ffmpeg -y -f lavfi -i "flite=textfile=line.txt:voice=slt" -af loudnorm=I=-16 -ar 44100 voice.mp3

On macOS, say -o voice.aiff -f line.txt works too. On Linux and Windows, espeak-ng -w voice.wav -f line.txt does. These voices sound robotic, so keep them for drafts. Put them behind the same interface as your paid voice, so switching is one environment variable:

interface VoiceProvider { name: string; speak(text: string, outPath: string): Promise<void> }

Step 6: join the scenes without re-encoding

What goes wrong: joining the clips is slow and loses quality, or the audio drifts out of sync.

Everyday example: joining a 40-scene video crawls along because every frame is compressed again, or halfway through, the voice starts to lag behind the picture.

Why it happens. Re-encoding means decoding the video and compressing it again, which is slow and loses a bit of quality each time. ffmpeg's concat demuxer can join clips without re-encoding, but only if every clip was encoded the same way.

The fix: encode every scene with identical settings (resolution, frame rate, pixel format, codec, audio sample rate and channel count), then join them:

printf "file '%s'\n" scene-0.mp4 scene-1.mp4 scene-2.mp4 > list.txt
ffmpeg -y -f concat -safe 0 -i list.txt -c copy -movflags +faststart final.mp4

-c copy copies the video and audio as they are, so it's almost instant.
+faststart moves the file's index to the front, so the video starts playing in a browser before it has fully downloaded.

If concat complains or the audio drifts, one clip was encoded differently. Usually it's a mono voice file that skipped -ac 2.

Step 7: survive real APIs

What goes wrong: renders that work on your laptop fail in production.

Everyday example: the image API answers "429 Too Many Requests" on scene 12 of 40, and the whole job dies. You retry it, and it pays for a new LLM plan before failing again.

Why it happens. Real APIs have rate limits and bad moments. Some errors fix themselves if you wait. Others never will, like a wrong API key.

The fix: three rules.

Retry only errors that can fix themselves. Retry 429 and 5xx with exponential backoff (wait 1 s, then 2 s, then 4 s) plus jitter (a small random extra wait, so many jobs don't retry at the same instant). Don't retry 400, 401 or 403. Fail the job at once with a clear message instead of burning credits.
Save finished steps on the job. Store the validated plan on the job record. When the job retries after an image failure, it skips the LLM call it already paid for.
Limit how much runs at once. Render, say, 3 scenes at a time and 2 jobs at a time, and make both configurable. Firing 40 requests at once with Promise.all is how you get rate-limited.

For one machine, a simple file-based job store is enough: one job.json per job, written atomically, plus a worker loop that picks up queued jobs. On startup, put any job still marked running back in the queue, so a crash doesn't strand it. When you outgrow one machine, put Redis/BullMQ or Postgres SKIP LOCKED behind the same interface.

The checklist

Validate the LLM's JSON. Clamp scene count and durations.
Scale up, crop to the target shape, then zoompan.
Measure the voice with ffprobe. Scene length = max(planned, speech + 0.25 s).
SRT chunks of 3 to 4 words, burned in with subtitles. Font size is in 288-unit canvas terms, not pixels.
Run ffmpeg in the asset folder. Text goes in files.
Identical encode settings, then concat -c copy with +faststart.
Retry only what's retryable, keep the plan on the job, limit concurrency.

Questions about any of the ffmpeg filters above? Ask in the comments and I'll answer.

7 ways Stripe webhooks break in production (and the code that fixes each)

Syncoders — Mon, 26 Oct 2026 08:31:51 +0000

TL;DR

Check the signature on the raw request body, never on re-built JSON.
Stripe can send the same event twice. Save each event ID first and skip repeats.
Return 200 only when the work is really done. Use a short "lease" so a slow or crashed attempt can't swallow an event.
Events can arrive out of order. Ask Stripe for the current state instead of trusting the event.
Guest buyers' emails are in customer_details.email, not customer_email.
Grant access from the webhook, never from the success page.
A failed renewal should start reminder emails, not an instant downgrade.

A few words first

Webhook: an HTTP POST that Stripe sends to your server when something happens, like a payment succeeding.
Endpoint: the URL on your server that receives it, e.g. /api/webhooks/stripe.
Event: the JSON inside that POST. Each one has a unique id (like evt_123) and a type (like checkout.session.completed).
Status code: the number you answer with. 2xx (e.g. 200) means "got it, done". Anything else means "that didn't work".

How a healthy endpoint works

Every request should go through these five steps. Three facts about Stripe explain why:

Stripe may send an event more than once. If your endpoint is slow, returns an error, or the connection drops before Stripe sees your 200, Stripe sends the event again. In live mode it keeps retrying, with growing gaps, for up to three days. You can also resend any event by hand from the Dashboard.
Stripe doesn't promise any order. An older event can arrive after a newer one.
Your status code is the only thing Stripe listens to. A 2xx stops the retries. Anything else schedules another try.

Each of the seven bugs below breaks one of the five steps. The code uses a Next.js App Router route handler, but the ideas work the same in Express, FastAPI or anything else that speaks HTTP.

1. Checking the signature on parsed JSON

What goes wrong: every webhook fails signature verification, even though your secret is correct.

Everyday example: you deploy, the first real payment comes in, and your logs fill with 400 errors. Nobody gets what they paid for.

Why it happens. Stripe signs each webhook so you can prove it really came from Stripe. The signature is a code computed from the request body and your webhook secret (whsec_...), sent in the Stripe-Signature header. The method is HMAC-SHA256, a standard way to prove a message came from someone who knows the secret and wasn't changed on the way.

The signature covers the exact bytes Stripe sent. Many frameworks parse the JSON before your code runs. If you then rebuild it with JSON.stringify(), the spacing and line breaks no longer match what Stripe sent. Different bytes give a different HMAC, so the check fails every time.

The tempting "fix" is to switch verification off. That lets anyone on the internet send your server a fake "payment succeeded" event.

The fix: read the body as raw text and hand that to Stripe's library.

// app/api/webhooks/stripe/route.ts
import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(req: Request) {
  const raw = await req.text();                    // the exact bytes Stripe sent
  const sig = req.headers.get("stripe-signature");
  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(raw, sig!, process.env.STRIPE_WEBHOOK_SECRET!);
  } catch {
    return new Response("bad signature", { status: 400 });
  }
  return handle(event);                            // steps 3 to 5, shown below
}

Other frameworks:

Express: put express.raw({ type: "application/json" }) on the webhook route only.
FastAPI: use await request.body().
Django: use request.body.

Keep the five-minute window. By default the library rejects a signature more than 300 seconds old. That stops someone who captured one real request from replaying it next week. Stripe signs every retry again with a fresh timestamp, so this never blocks a real retry.

2. Doing the work twice

What goes wrong: one purchase triggers two of everything.

Everyday example: Stripe sends the same event twice, and the customer gets two welcome emails and two licence keys.

Why it happens. Stripe would rather send an event twice than lose it. If your 200 gets lost on the way back, Stripe never sees it and sends the event again. Your handler runs a second time.

The fix: make the handler idempotent. Idempotent means that running it twice has the same effect as running it once.

The standard way is to save each event.id in a table where the ID is the primary key. That is a unique constraint: the database refuses a second row with the same ID. Before doing any work, try to insert the ID. If a finished row is already there, skip the event and return 200.

The order matters: save the ID first, then do the work. If you first ask "have I seen this ID?" and only save it at the end, two copies arriving at the same moment both see "no" and both run. With the insert first, the database lets exactly one of them win.

There's one more case to handle before this is safe, and it's in the next section, together with the code.

3. Telling Stripe "done" when the work isn't done

What goes wrong: Stripe is told an event succeeded, so it stops retrying, but the work never happened.

Everyday example 1: your database is down for a minute. The handler logs the error and returns 200 anyway. The customer paid, and their plan never updates.

// Don't do this: a failure looks like success to Stripe
try { await dispatch(event); } catch (e) { console.error(e); }
return new Response("ok");

Everyday example 2: your handler is waiting on a slow API, so Stripe gives up on it and retries. The retry sees the event ID is already saved, answers 200 "duplicate", and Stripe stops. Then the first attempt fails. Again, the customer paid and got nothing.

Why it happens. Your status code is the only thing Stripe listens to. In example 2, a plain "seen it" row can't tell "finished" apart from "still running" or "crashed halfway".

The fix: return an error whenever the work isn't finished, and use a claim with a lease. A lease is a claim with an expiry time: "I'm working on evt_123 until 12:01:00". Each row gets a status (processing or done) and a locked_until time. When an event arrives:

No row yet: insert one. This attempt owns the event.
done: it's a duplicate. Return 200.
processing, lease still valid: another attempt is working on it. Return 409, so Stripe tries again later.
processing, lease expired: the earlier attempt crashed. Take the event over.

In Postgres, a single statement makes the claim. It either inserts a new row or takes over an expired lease, with no gap where two attempts can both win:

CREATE TABLE processed_events (
  id           text PRIMARY KEY,                     -- the Stripe event id
  status       text NOT NULL DEFAULT 'processing',   -- 'processing' or 'done'
  locked_until timestamptz NOT NULL                  -- when the lease runs out
);

-- Claim: returns a row only if this attempt now owns the event
INSERT INTO processed_events (id, locked_until)
VALUES ($1, now() + interval '60 seconds')
ON CONFLICT (id) DO UPDATE
  SET locked_until = now() + interval '60 seconds'
  WHERE processed_events.status = 'processing'
    AND processed_events.locked_until < now()
RETURNING id;

If no row comes back, read the row's status: done means duplicate, anything else means busy. The handler then looks like this:

async function handle(event: Stripe.Event) {
  const claim = await db.claimEvent(event.id);     // "claimed" | "duplicate" | "busy"
  if (claim === "duplicate") return new Response("duplicate", { status: 200 });
  if (claim === "busy") return new Response("in progress", { status: 409 });

  try {
    await dispatch(event);                         // update the DB, send the email
    await db.markDone(event.id);                   // status = 'done'
    return new Response("ok", { status: 200 });
  } catch (err) {
    await db.releaseEvent(event.id);               // locked_until = now(), so a retry can run it
    console.error("webhook failed", event.type, event.id, err);
    return new Response("retry", { status: 500 });
  }
}

Two rules keep this safe:

Make the lease longer than your slowest run. Give your Stripe client a timeout, e.g. new Stripe(key, { timeout: 8000, maxNetworkRetries: 2 }), so one hung call can't outlast the lease.
Keep the handler short. If provisioning takes 20 seconds, write what you need to the database, put the slow part on a queue keyed by event.id, and return.

Return 200 only when the work is committed, or when you're deliberately ignoring an event type you don't handle.

4. Trusting the order events arrive in

What goes wrong: a customer who cancelled gets their paid plan back.

Everyday example: a customer cancels at 12:00:05. An older "subscription updated, status active" event from 12:00:01 was delayed by a retry and arrives after the cancel. Your code applies it, and the cancelled customer has Pro again.

Why it happens. Stripe doesn't guarantee delivery order. A retried event arrives whenever its retry runs, which can be after newer events.

The fix: treat the event as a nudge, not as the truth. When a subscription event arrives, ask Stripe for the subscription as it is right now and save that:

case "customer.subscription.updated":
case "customer.subscription.deleted": {
  const sub = event.data.object as Stripe.Subscription;
  const current = await stripe.subscriptions.retrieve(sub.id);  // the state right now
  await db.saveSubscription(current);   // "active", "past_due", "canceled", ...
  break;
}

A cheaper option is to compare event.created with the timestamp of the last event you applied and skip older ones. But event.created is in whole seconds, so two events in the same second tie. Re-fetching costs one API call and always gives the current state, so it's the one I'd pick.

5. Looking up the buyer by `customer_email`

What goes wrong: some buyers pay and get nothing, with no error anywhere.

Everyday example: you share a Payment Link on social media and ten people buy. Your code looks for customer_email, finds null every time, and none of them get access.

Why it happens. A Payment Link is a checkout page you create in the Stripe Dashboard without writing code. The checkout.session.completed event has two email fields, and they mean different things:

customer_email is the email you passed in when your code created the session. For Payment Links, pricing tables and most guest checkouts it's null.
customer_details.email is the email the buyer typed on the Checkout page.

Code that reads only customer_email passes every test where you created the session yourself, then silently drops every Payment Link order in production.

The fix: identify the buyer by your own ID first, then fall back to the email they typed. client_reference_id is an ID you can attach when you create a session, such as your user ID.

case "checkout.session.completed": {
  const s = event.data.object as Stripe.Checkout.Session;
  if (s.payment_status !== "paid" && s.payment_status !== "no_payment_required") break;
  const userId = s.client_reference_id ?? s.metadata?.userId;
  const email = s.customer_details?.email ?? s.customer_email;
  await provision({ userId, email, customerId: s.customer as string | null });
  break;
}

Also check payment_status. With delayed payment methods, like bank debits, the session completes before the money arrives. The money is confirmed later by a separate checkout.session.async_payment_succeeded event, so provision there too.

6. Granting access on the success page

What goes wrong: people get access without paying, or paid customers land on a broken page.

Everyday example: your /thanks page turns on Pro when it loads. Someone posts the link in a Discord server, and everyone who opens it gets Pro for free.

Why it happens. The success_url is just the page the buyer's browser goes to after Checkout. Anyone can open it, and anyone can share it.

The fix: grant access only from the webhook. Treat the success page as a status screen: show "Thanks, we're confirming your payment" and ask your own API whether the webhook has run yet.

The success page still needs to know which checkout it belongs to. Stripe replaces the literal text {CHECKOUT_SESSION_ID} in your success_url with the real session ID. That's where a sneaky bug lives. In a JavaScript template literal (a backtick string), ${...} inserts a variable:

// Bug: ${CHECKOUT_SESSION_ID} is a JavaScript variable lookup
success_url: `${base}/thanks?session_id=${CHECKOUT_SESSION_ID}`,

// Correct: no $, so Stripe sees the literal text and fills it in
success_url: `${base}/thanks?session_id={CHECKOUT_SESSION_ID}`,

The buggy line throws a ReferenceError, or produces session_id=undefined if a variable with that name happens to exist. Building the URL with new URL() and searchParams.set() breaks it a third way: the braces get encoded to %7BCHECKOUT_SESSION_ID%7D, and Stripe no longer recognises them. Searching your code for success_url takes a minute.

7. Cutting access on the first failed renewal

What goes wrong: good customers get locked out over a card problem that would have fixed itself.

Everyday example: a customer's card expired last month. The renewal fails at 3 a.m., your code downgrades them on the spot, and they wake up locked out, even though Stripe was going to retry the charge.

Why it happens. invoice.payment_failed fires when a renewal charge is declined. It's tempting to treat it as "they stopped paying". But Stripe retries the card on its own schedule (Smart Retries), and the customer can still update their card.

The fix: use the event to start dunning, the process of reminding a customer to fix a failed payment. Email them a link to update their card. Let access follow the subscription's status as Stripe moves it from past_due to unpaid or canceled, depending on your settings.

case "invoice.payment_failed": {
  const invoice = event.data.object as Stripe.Invoice;
  await sendUpdateCardEmail(invoice.customer as string);  // a reminder, not a downgrade
  break;
}

// Access comes from the subscription status, not from the failed invoice.
// Including "past_due" gives a grace period while Stripe retries; leave it out if you don't want one.
const hasAccess = (status: Stripe.Subscription.Status) =>
  status === "active" || status === "trialing" || status === "past_due";

Testing all of this without a Stripe account

You can test every case offline, because Stripe's library can sign test payloads for you:

import Stripe from "stripe";
const stripe = new Stripe("sk_test_dummy");
const secret = "whsec_test_secret";

const payload = JSON.stringify(event);   // a fixture shaped like a real Stripe event
const header = stripe.webhooks.generateTestHeaderString({ payload, secret });
// POST the payload with this "stripe-signature" header to your handler

Then write one test per case:

Duplicate. Send the same signed event twice. Expect two 200s and one side effect.
Slow attempt. Make the work slow and send a second copy while it runs. Expect 409, then a 200 on a later copy, and one side effect.
Crash. Claim an event, then stop before finishing. After the lease runs out, a new copy should process it.
Failure. Make the database throw. Expect 500, and the event not marked done.
Out of order. Send deleted, then the older updated (active). Expect the subscription to stay canceled.
Old signature. Sign with a timestamp an hour old (timestamp: now - 3600). Expect 400.
Tampered. Change one byte of the body after signing. Expect 400.
Wrong secret. Sign with a different whsec_. Expect 400.
Guest checkout. Send client_reference_id: null, customer_email: null and customer_details.email: "a@b.com". Expect the buyer to get access.

Before going live, also run stripe listen --forward-to localhost:3000/api/webhooks/stripe, trigger each event type, and resend one old event from the Dashboard to confirm nothing happens twice.

The short version

Verify the raw body. Keep the five-minute window.
Save event.id first, under a unique constraint.
Return 200 only when the work is done. Use a lease, answer 409 while busy, and release the claim on failure.
Don't trust arrival order. Re-fetch the subscription.
Find buyers by your own ID, then customer_details.email.
Grant access from the webhook, never from the success page. Keep {CHECKOUT_SESSION_ID} literal.
A failed renewal starts reminder emails, not a downgrade.

Before you go live, I keep a free Stripe Webhooks Go-Live Checklist (pay what you want, $0 is fine) that covers what to check before you trust your endpoint with live money.

If you'd rather not build the event ledger, leases and retries yourself, Webhook-Proof Stripe is my paid kit that does them for Next.js and FastAPI.

DEV Community: Syncoders

Building an AI Shorts pipeline with ffmpeg: 9:16, Ken Burns zoom, captions that match the voice

A few words first

The whole pipeline

Step 1: get a scene plan you can trust

Step 2: turn a still image into a moving 9:16 clip

Step 3: make each scene as long as its voice

Step 4: burn in captions that follow the voice

Step 5: a free voice for drafts

Step 6: join the scenes without re-encoding

Step 7: survive real APIs

The checklist

7 ways Stripe webhooks break in production (and the code that fixes each)

A few words first

How a healthy endpoint works

1. Checking the signature on parsed JSON

2. Doing the work twice

3. Telling Stripe "done" when the work isn't done

4. Trusting the order events arrive in

5. Looking up the buyer by customer_email

6. Granting access on the success page

7. Cutting access on the first failed renewal

Testing all of this without a Stripe account

The short version

5. Looking up the buyer by `customer_email`