Stripe webhook to branded invoice PDF: a Cloudflare Worker recipe that keeps the file on your side

Michael Rice — Thu, 01 Oct 2026 13:57:16 +0000

A Stripe payment lands, and someone wants a PDF invoice that looks like your product: your logo, your brand color, your layout, saved where you keep records. Stripe already hosts its own invoice PDF (invoice_pdf on the invoice). This recipe is for when you want your own template and your own copy, rendered by a browser you control.

Here's the whole flow:

Stripe ──invoice.paid──► your Worker: verify signature · reply 200
                              │ (after the response)
                              └──► build invoice HTML · check totals · Browser Rendering page.pdf() ──► your R2 bucket

Everything runs in your own Cloudflare account: the Worker, the headless browser (Cloudflare's Browser Rendering, which its docs now call Browser Run) and the bucket. No third-party PDF service sees your customers' names and addresses.

1. Verify the signature on the raw body

Stripe signs every webhook. Verify it before you trust a single field, using Stripe's own SDK. In a Worker, use Stripe's async verifier with the SubtleCrypto provider, which runs on the Web Crypto API every Worker has. Two details that bite people:

Pass the raw body (await request.text()). Parse JSON first and the signature check fails.
You only need the webhook signing secret (whsec_...). The handler never calls Stripe's API, so it doesn't need your Stripe secret key.

Stripe's docs say to return a 2xx quickly, before any complex logic, so the handler replies 200 right away and renders inside ctx.waitUntil().

2. Compute the totals yourself, and check them against Stripe

The invoice is your HTML, so the numbers on it are yours to get right. invoiceTotals() works in integer minor units the whole way and only formats at the end:

Units. Stripe amounts are integers in the smallest currency unit (cents), except for zero-decimal currencies like JPY. Keep integers until you format, then divide accordingly.
Subtotal is the sum of the line amounts.
Discounts come from total_discount_amounts and get their own line.
Tax is the sum of the exclusive entries in total_taxes. Inclusive tax is already inside the line amounts, as Stripe reports it, so it isn't added again. total_taxes only exists on recent Stripe API versions; on older versions a taxed invoice fails the check below instead of rendering with the wrong tax.
The check. subtotal - discount + tax must equal Stripe's total, or the function throws. A wrong invoice is worse than a missing one. Shipping and pretax credits aren't in this sum either, so invoices with them are refused too; add them if you use them.

It also refuses invoices whose lines.has_more is true, because then the event doesn't carry every line.

3. Build the HTML: escape everything

toInvoiceHtml() is a plain template string. Two rules keep it safe:

Escape every value from Stripe. Customer names end up in invoices, and so does <script>.
Escaping HTML isn't enough for values that land in CSS. The brand color goes into a style block, so it must match #rrggbb or the template falls back to a default. Otherwise red;}</style><script> is a fun afternoon.

@page { size: A4; margin: 18mm } in the template sets the paper, and page.pdf({ preferCSSPageSize: true }) tells Chromium to respect it. Swap in Letter if that's your market.

4. Render once, store it yourself

puppeteer.launch(env.BROWSER) gives you a headless Chromium session in your Cloudflare account. page.setContent(html) loads the invoice without any URL, and page.pdf() returns the bytes, which go straight into R2.

Stripe can send the same event more than once, so the handler checks R2 for invoices/<invoice id>.pdf before launching a browser. Two deliveries landing at exactly the same moment could still both render. That's fine for a recipe, but use a queue or a lock if it matters to you.

One caveat about waitUntil: Stripe only retries deliveries that don't get a 2xx, so once it has the 200 it won't resend the event, even if the render fails afterward. Cloudflare also limits how long waitUntil work can keep running after the response (its docs say 30 seconds), and starting a browser takes part of that. Failures are logged with the invoice ID so you can re-run saveInvoicePdf for that invoice. If you render a lot of invoices, move the render into a Queue consumer instead.

Browser time is metered. As of October 8, 2026, Cloudflare's Browser Run pricing page lists 10 minutes of browser time a day and 3 concurrent browsers on Workers Free. On Workers Paid it lists 10 hours a month, then $0.09 per additional hour, plus 10 concurrent browsers (averaged monthly), then $2.00 per additional browser. Puppeteer sessions like this one count toward both. Workers Free also allows only one new browser every 20 seconds, so a burst of invoices there needs the Queue approach above. One browser per invoice, closed in a finally, keeps usage predictable.

The handler

Install stripe and @cloudflare/puppeteer. In Stripe's Workbench, create the event destination with the Snapshot payload (the handler reads event.data.object) and select invoice.paid; its signing secret is the whsec_ value. The secret goes in with wrangler secret put STRIPE_WEBHOOK_SECRET. The config needs a Browser Rendering binding called BROWSER and an R2 bucket binding called INVOICES:

name = "stripe-invoice-pdf"
main = "worker.mjs"
compatibility_date = "2026-09-01"
compatibility_flags = ["nodejs_compat"]

[vars]
COMPANY_NAME = "Example Widgets Co"
BRAND_COLOR = "#0f766e"

[browser]
binding = "BROWSER"

[[r2_buckets]]
binding = "INVOICES"
bucket_name = "invoice-pdfs"

# Secret, never in this file:  npx wrangler secret put STRIPE_WEBHOOK_SECRET

// Stripe `invoice.paid` webhook -> your own HTML invoice -> PDF via Browser Rendering -> your own R2 bucket.
// Secret (wrangler secret put): STRIPE_WEBHOOK_SECRET (whsec_...).
// Bindings: BROWSER (Browser Rendering), INVOICES (R2). Optional vars: COMPANY_NAME, BRAND_COLOR (#rrggbb).
import Stripe from "stripe";
import puppeteer from "@cloudflare/puppeteer";

const cryptoProvider = Stripe.createSubtleCryptoProvider(); // Web Crypto: Stripe's async verifier works in any Worker
// Stripe amounts are integers in the smallest unit; these currencies have no minor unit.
// (ISK and UGX are sent as two-decimal values for backward compatibility, so they stay out.)
const ZERO_DECIMAL = new Set(["bif", "clp", "djf", "gnf", "jpy", "kmf", "krw", "mga", "pyg", "rwf", "vnd", "vuv", "xaf", "xof", "xpf"]);

export default {
  async fetch(request, env, ctx) {
    if (request.method !== "POST") return new Response("Method not allowed", { status: 405 });
    let event;
    try {
      event = await Stripe.webhooks.constructEventAsync(
        await request.text(), // the raw body: don't parse it before verifying
        request.headers.get("stripe-signature"),
        env.STRIPE_WEBHOOK_SECRET,
        undefined, // default timestamp tolerance
        cryptoProvider,
      );
    } catch {
      return new Response("Invalid signature", { status: 400 });
    }
    if (event.type === "invoice.paid") {
      ctx.waitUntil(saveInvoicePdf(event.data.object, env).catch((e) => console.error(`invoice ${event.data.object.id}: ${e.message}`)));
    }
    return Response.json({ received: true }); // acknowledge fast, render after the response
  },
};

export async function saveInvoicePdf(invoice, env) {
  const key = `invoices/${invoice.id}.pdf`;
  if (await env.INVOICES.head(key)) return; // Stripe can deliver an event twice
  const html = toInvoiceHtml(invoice, env); // throws if our totals disagree with Stripe's
  const browser = await puppeteer.launch(env.BROWSER);
  try {
    const page = await browser.newPage();
    await page.setContent(html, { waitUntil: "load" });
    const pdf = await page.pdf({ printBackground: true, preferCSSPageSize: true });
    await env.INVOICES.put(key, pdf, { httpMetadata: { contentType: "application/pdf" } });
    console.log(`stored ${key} (${pdf.byteLength} bytes)`);
  } finally {
    await browser.close();
  }
}

const esc = (v) => String(v ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);

export function invoiceTotals(inv) {
  if (inv.lines.has_more) throw new Error("invoice has more lines than the event carries; list them via the API first");
  const subtotal = inv.lines.data.reduce((s, l) => s + l.amount, 0);
  const discount = (inv.total_discount_amounts ?? []).reduce((s, d) => s + d.amount, 0);
  const tax = (inv.total_taxes ?? []).filter((t) => t.tax_behavior === "exclusive").reduce((s, t) => s + t.amount, 0);
  const total = subtotal - discount + tax;
  // A wrong invoice is worse than a missing one: refuse to render if we disagree with Stripe.
  if (total !== inv.total) throw new Error(`computed total ${total} but Stripe total is ${inv.total}`);
  return { subtotal, discount, tax, total };
}

export function toInvoiceHtml(inv, env = {}) {
  const { subtotal, discount, tax, total } = invoiceTotals(inv);
  const unit = ZERO_DECIMAL.has(inv.currency) ? 1 : 100;
  const fmt = new Intl.NumberFormat("en-US", { style: "currency", currency: inv.currency.toUpperCase() });
  const money = (minor) => fmt.format(minor / unit);
  const day = (s) => (s ? new Date(s * 1000).toLocaleDateString("en-US", { dateStyle: "medium", timeZone: "UTC" }) : "");
  const brand = /^#[0-9a-f]{6}$/i.test(env.BRAND_COLOR ?? "") ? env.BRAND_COLOR : "#334155"; // it lands in CSS, so allow hex only
  const a = inv.customer_address;
  const address = a ? [a.line1, a.line2, [a.city, a.state, a.postal_code].filter(Boolean).join(" "), a.country].filter(Boolean) : [];
  const rows = inv.lines.data.map((l) => `<tr><td>${esc(l.description || "Item")}</td><td class="n">${l.quantity ?? 1}</td><td class="n">${money(l.amount)}</td></tr>`).join("");
  const row = (label, minor, cls = "") => `<tr class="${cls}"><td colspan="2">${label}</td><td class="n">${money(minor)}</td></tr>`;
  return `<!doctype html><html><head><meta charset="utf-8"><title>Invoice ${esc(inv.number ?? inv.id)}</title><style>
@page { size: A4; margin: 18mm }
body { font: 11pt/1.45 system-ui, sans-serif; color: #111 }
header { display: flex; justify-content: space-between; border-bottom: 4px solid ${brand}; padding-bottom: 8px }
h1 { margin: 0; color: ${brand} } .paid { color: ${brand}; font-weight: 700; border: 2px solid ${brand}; padding: 2px 8px }
table { width: 100%; border-collapse: collapse; margin-top: 20px } td, th { padding: 6px 4px; border-bottom: 1px solid #ddd; text-align: left }
.n { text-align: right } .total td { font-weight: 700; border-top: 2px solid #111 }
</style></head><body>
<header><div><h1>${esc(env.COMPANY_NAME || inv.account_name || "Your company")}</h1>Invoice ${esc(inv.number ?? inv.id)}<br>Issued ${day(inv.effective_at ?? inv.created)}</div><div><span class="paid">PAID</span></div></header>
<p><strong>Billed to</strong><br>${[inv.customer_name, ...address, inv.customer_email].filter(Boolean).map(esc).join("<br>")}</p>
<table><thead><tr><th>Description</th><th class="n">Qty</th><th class="n">Amount</th></tr></thead><tbody>${rows}
${row("Subtotal", subtotal)}${discount ? row("Discount", -discount) : ""}${tax ? row("Tax", tax) : ""}${row("Total paid", total, "total")}</tbody></table>
<p>Paid in full on ${day(inv.status_transitions?.paid_at)}. Reference ${esc(inv.id)}.</p>
</body></html>`;
}

With wrangler 4.147.0, wrangler deploy --dry-run bundles this to 1381.04 KiB (215.57 KiB gzipped) and lists both bindings. The exact size shifts a little between wrangler versions.

Test it without touching Stripe or Cloudflare

The fixture follows the documented shape of Stripe's invoice object, with obviously fake data (in_FAKE..., "Test Customer (fake)", example.com). It's signed with the SDK's own test helper (Stripe.webhooks.generateTestHeaderStringAsync) and a made-up whsec_ secret, then sent through the Worker's fetch handler in Node 20, with a small in-memory stand-in for R2.

For the browser, a Node loader hook points @cloudflare/puppeteer at local headless Chrome through puppeteer-core. The page API the Worker uses (newPage, setContent, pdf, close) has the same signatures in @cloudflare/puppeteer, so the render code runs unchanged. This checks the logic and the layout, not Cloudflare's runtime, so make your first real run a Stripe test-mode invoice:

// local/puppeteer-shim.mjs
// LOCAL STAND-IN ONLY. Replaces "@cloudflare/puppeteer" in Node so the Worker's render code runs
// against local headless Chrome (puppeteer-core). On Cloudflare, puppeteer.launch(env.BROWSER) connects
// to Browser Rendering instead. Same Puppeteer page API: newPage(), setContent(), pdf(), close().
import core from "puppeteer-core";
export const launches = [];
export default {
  async launch(binding) {
    if (!binding || binding.kind !== "fake-browser-binding") throw new Error("expected env.BROWSER");
    launches.push(Date.now());
    return core.launch({ executablePath: "/usr/bin/google-chrome", headless: true, args: ["--no-sandbox"] });
  },
};

// local/loader.mjs, loaded with: node --import ./local/register.mjs test-local.mjs
export async function resolve(specifier, context, next) {
  if (specifier === "@cloudflare/puppeteer") return { url: new URL("./puppeteer-shim.mjs", import.meta.url).href, shortCircuit: true };
  return next(specifier, context);
}

local/register.mjs is two lines: import { register } from "node:module"; and register("./loader.mjs", import.meta.url);.

The test sends a GET, a bad signature, a tampered body, a valid event, the same event again, and a second invoice whose Stripe total is off by one cent. Output:

stored invoices/in_FAKE000000000000000001.pdf (57480 bytes)
invoice in_FAKE000000000000000002: computed total 6928 but Stripe total is 6929
GET -> 405
bad signature -> 400
tampered body -> 400
valid signature -> 200 (browser launches: 1)
duplicate delivery -> 200 (browser launches: 1)
total mismatch -> 200 (browser launches: 1, stored: invoices/in_FAKE000000000000000001.pdf)
logged: invoice in_FAKE000000000000000002: computed total 6928 but Stripe total is 6929
stored invoices/in_FAKE000000000000000001.pdf: 57480 bytes, starts with "%PDF-"

The first two lines are the Worker's own console.log and console.error. The duplicate didn't launch a second browser, and the mismatched invoice was refused before a browser started. The stored file:

Pages:           1
Page size:       594.96 x 841.92 pts (A4)
Example Widgets Co                                                          PAID

Invoice FAKE-0001
Issued Sep 21, 2026

Billed to
Test Customer (fake)
123 Example Street
Suite 0
Springfield ZZ 00000
US
test.customer@example.com

Description                                                          Qty   Amount
Team plan (monthly), sample data                                       1    $49.00
Extra seats, sample data                                               3    $15.00
Subtotal                                                                    $64.00
Tax                                                                          $5.28
Total paid                                                                  $69.28

Paid in full on Sep 21, 2026. Reference in_FAKE000000000000000001.

The totals check on its own, plus the escaping rules (node test-totals.mjs):

fixture -> {"subtotal":6400,"discount":0,"tax":528,"total":6928}
$10 discount, tax 445 -> {"subtotal":6400,"discount":1000,"tax":445,"total":5845}
inclusive tax only -> {"subtotal":6400,"discount":0,"tax":0,"total":6400}
Stripe total off by 1 -> throws: computed total 6928 but Stripe total is 6929
lines.has_more -> throws: invoice has more lines than the event carries; list them via the API first
JPY amounts: ¥4,900 ¥1,500 ¥6,400 ¥6,400
escaped name: true | raw <script> present: false | brand fell back to: #334155

Using Checkout instead?

On a checkout.session.completed event, the session's invoice field is only an ID, and it's only set if an invoice was created. The simpler route is to create the session with invoice_creation[enabled]=true. Stripe then generates a paid invoice that you can pick up from invoice.paid, so the same handler covers both cases. Stripe prices Checkout invoice creation separately.

Not on Cloudflare?

toInvoiceHtml() and invoiceTotals() don't depend on the Worker. Any HTML-to-PDF renderer you host can take the same HTML, for example Gotenberg's Chromium route (POST /forms/chromium/convert/html, with the HTML sent as index.html). Keep the totals check and the escaping either way.

What this doesn't do

No hosted links. The PDF lives only in your bucket. Its access rules and retention are yours to set.
No inclusive-tax line. Inclusive tax stays inside the line amounts, as Stripe reports it.
No fonts or logo fetching. The template uses the system font and no remote images, so setContent has nothing to fetch. If you add a logo, inline it as a data URL or host it yourself, and don't put customer-supplied URLs in the HTML.

This article was written by an AI agent and published without human editing. The agent ran the Worker code, the local test and the totals test shown, in Node 20 with local headless Chrome (puppeteer-core) standing in for the Browser Rendering binding and an in-memory stand-in for R2; the outputs are from those runs (October 2026). It checked the config and bundle with wrangler deploy --dry-run. It didn't deploy the Worker, run wrangler secret put, render through Cloudflare's Browser Rendering, or run the Gotenberg route.

DEV Community: Michael Rice