Forem: Digital Troubadour

Generating PDFs from HTML in Node.js (and why I stopped using Puppeteer)

Digital Troubadour — Wed, 18 Mar 2026 06:03:52 +0000

Last year I was adding invoice generation to a side project. Three days later I was still debugging Puppeteer on a DigitalOcean droplet.

Blank PDFs, fonts not loading, the process eating 400+MB of RAM for a single render.

I shipped something that worked 90% of the time and crossed my fingers.

If that sounds familiar, here's what I've learned since.

What's actually wrong with Puppeteer

Nothing, on your laptop. The problems start when you deploy.

Memory. Chromium is a full browser. Each instance takes 300–500MB. If a render crashes mid-way, the browser process doesn't always clean up after itself. Run this under any real traffic and you'll watch your server slowly run out of memory.

Cold starts. Spinning up a Chromium instance takes 1–3 seconds. Every time. If you're on a serverless function that scales to zero, that latency hits every first request.

Fonts and assets. Puppeteer runs sandboxed. Anything loaded from a relative path or file:// URL either fails silently or renders wrong. The PDF looks fine locally, looks broken in production. You spend an hour figuring out why.

Server dependencies. Chromium needs libglib, libnss, libatk, and a handful of other system libraries that aren't on a vanilla Ubuntu server. Every new environment is a fresh debugging session. Every Docker image is 400MB heavier.

None of this is Puppeteer's fault — it's a browser automation tool being asked to do something it wasn't really designed for.

The other options people try

wkhtmltopdf

Uses WebKit to render HTML. Fast, lightweight, no browser process to manage. The catch: it hasn't been maintained since 2020 and CSS support is frozen around 2013. No flexbox, no grid, no CSS variables. If your template uses any modern layout it'll look wrong.

Fine if you're generating PDFs from HTML that was already simple. Not fine if you're building something new.

PDFKit / jsPDF

You describe the document in code — place text at this coordinate, draw a line here, set this font. Very precise, and works well for documents with fixed layouts.

The problem is you can't reuse HTML templates. Everything has to be rebuilt in the library's API. A simple invoice with a dynamic line-item table takes a surprising amount of code to get right. Any design change means editing that code.

An API

Send HTML, get a PDF back. The rendering infrastructure is someone else's problem. No Chromium to manage, no system dependencies, nothing to deploy.

This is where most teams land after they've burned enough time on the alternatives.

What using an API actually looks like

Here's a basic Node.js example using LightningPDF:

const response = await fetch("https://lightningpdf.dev/api/v1/pdf/generate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    html: `
      <html>
        <head><script src="https://cdn.tailwindcss.com"></script></head>
        <body class="p-8 font-sans">
          <h1 class="text-2xl font-bold">Invoice #1042</h1>
          <p class="text-gray-500 mt-1">Due: March 31, 2026</p>
        </body>
      </html>
    `,
    options: { format: "A4" }
  })
});

const { data } = await response.json();
const pdfBuffer = Buffer.from(data.pdf, "base64");

That's it. Your existing HTML templates work as-is. Tailwind classes work without a build step. The migration from Puppeteer is mostly just deleting the browser setup and teardown code.

Templates for documents you generate repeatedly

If you're generating invoices or reports where the structure is always the same but the data changes, you can build the template once in a visual designer and just pass data at render time:

body: JSON.stringify({
  template_id: "invoice-001",
  data: {
    company: "Acme Corp",
    invoice_number: "1042",
    items: [
      { name: "Web development", quantity: 10, price: 150 },
      { name: "Design review", quantity: 2, price: 200 }
    ]
  }
})

No HTML string concatenation in your app code. The template lives separately and gets filled in at render time.

Batch generation

For bulk jobs — end-of-month invoices, report runs — use the async endpoint and get a webhook when it's done:

const response = await fetch("https://lightningpdf.dev/api/v1/pdf/async", {
  method: "POST",
  headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    template_id: "monthly-statement",
    data: { user_id: "usr_123", month: "February" },
    webhook_url: "https://yourapp.com/webhooks/pdf-ready"
  })
});

Rough performance numbers

Approach	Typical render time	Memory overhead
Puppeteer (self-hosted)	2–4s	300–500MB per instance
wkhtmltopdf	0.5–1s	Low
API (simple docs)	<100ms	Not your problem
API (complex CSS)	1–3s	Not your problem

The speed difference for simple documents is significant. A Go-native renderer can produce a basic invoice in under 100ms. Chromium only kicks in when the HTML is complex enough to need it.

Is this worth it for a small project?

Probably yes, just because of deployment complexity. Even if you only generate 20 PDFs a month, not having to install Chromium on every server is worth something. Most PDF APIs have a free tier that covers low volume.

For anything with real traffic or batch generation, the difference is more obvious — you're not thinking about memory limits or process management at all.

What are you currently using for PDF generation? Curious if anyone has found a way to make self-hosted Puppeteer not terrible in production.

[Boost]

Digital Troubadour — Sat, 07 Mar 2026 05:54:14 +0000

HTML to PDF - The Complete Guide for 2026

Digital Troubadour ・ Mar 7

#programming #productivity #tutorial #automation

HTML to PDF - The Complete Guide for 2026

Digital Troubadour — Sat, 07 Mar 2026 05:54:01 +0000

HTML to PDF: The Complete Guide for 2026

Converting HTML to PDF is one of the most common requirements in modern web development. Whether you're building invoices, reports, receipts, or certificates, you need a reliable way to transform HTML into print-ready PDFs.

HTML-to-PDF conversion is the process of transforming HTML markup and CSS styles into a portable, print-ready PDF document, preserving layout, fonts, and images for offline viewing and distribution.

This comprehensive guide covers everything you need to know about HTML-to-PDF conversion in 2026, including the different approaches, common pitfalls, performance considerations, and how to choose the right solution for your needs.

Why HTML to PDF?

HTML is the universal language of the web. It offers:

Rich formatting: CSS for styling, layouts, and responsive design
Dynamic content: Template engines for variable data
Familiar tooling: Every developer knows HTML/CSS
Reusability: Same HTML can power web pages and PDFs

The challenge? Browsers render HTML to screens, not paper. Converting HTML to PDF requires specialized tools that understand print layouts, page breaks, and PDF specifications.

The Three Approaches

There are three main approaches to HTML-to-PDF conversion, each with tradeoffs:

1. Browser-Based (Headless Chrome/Chromium)

How it works: Launch a headless browser, load HTML, trigger print-to-PDF.

Tools: Puppeteer, Playwright, Selenium

Pros:

✅ Excellent CSS support (same as Chrome)
✅ JavaScript execution
✅ Renders exactly like browser
✅ Handles modern web features (flexbox, grid, animations)

Cons:

❌ Slow (1-3 seconds per PDF)
❌ Memory-intensive (100-300MB per instance)
❌ Requires infrastructure (Docker, K8s)
❌ Complex page break handling

Best for: Complex web layouts, modern CSS, JavaScript-heavy content

2. Library-Based (wkhtmltopdf, PrinceXML)

How it works: Specialized rendering engines that convert HTML to PDF without a full browser.

Tools: wkhtmltopdf, PrinceXML, WeasyPrint, pdfkit

Pros:

✅ Faster than browsers (500ms-2s)
✅ Lower memory usage
✅ Better page break control (CSS Paged Media)
✅ Designed for print

Cons:

❌ Limited CSS support (especially modern features)
❌ No JavaScript execution (mostly)
❌ Inconsistent rendering vs browsers
❌ Licensing costs (PrinceXML: $3,800+)

Best for: Print-focused documents, advanced page layout, when CSS Paged Media features are needed

3. API-Based (Managed Services)

How it works: Cloud-hosted services handle all infrastructure, scaling, and rendering.

Tools: LightningPDF, DocRaptor, PDFShift, CraftMyPDF

Pros:

✅ Zero infrastructure management
✅ Fast (sub-100ms with native engines)
✅ Template marketplaces
✅ Batch processing
✅ Automatic scaling

Cons:

❌ Recurring costs (vs one-time library purchase)
❌ External dependency
❌ Data leaves your infrastructure (API does not retain data after response)

Best for: Production applications, high volumes, teams wanting to focus on product not infrastructure

Comparison Table

Approach	Speed	Cost	Maintenance	CSS Support	Scaling
Puppeteer	⭐⭐ (1-3s)	Free*	⭐⭐ High	⭐⭐⭐⭐⭐ Full	Manual
wkhtmltopdf	⭐⭐⭐ (500ms)	Free	⭐⭐⭐ Low	⭐⭐ Limited	Manual
PrinceXML	⭐⭐⭐ (1-2s)	$3,800+	⭐⭐⭐ Low	⭐⭐⭐⭐ Excellent	Manual
LightningPDF	⭐⭐⭐⭐⭐ (<100ms)	$0.01/doc	⭐⭐⭐⭐⭐ None	⭐⭐⭐⭐⭐ Full	Automatic

*Free library, but infrastructure costs $200-500/month for production

Common Pitfalls and Solutions

1. Page Breaks

Problem: Content splits awkwardly across pages

Solution: Use CSS page break properties

/* Avoid page breaks inside elements */
.invoice-item {
    page-break-inside: avoid;
}

/* Force page break before element */
.new-section {
    page-break-before: always;
}

/* Control orphan/widow lines */
p {
    orphans: 3;
    widows: 3;
}

2. Missing Fonts

Problem: PDFs show default fonts instead of custom fonts

Solution: Embed fonts with @font-face or use web-safe fonts

@font-face {
    font-family: 'CustomFont';
    src: url('https://yoursite.com/fonts/custom.woff2') format('woff2');
}

body {
    font-family: 'CustomFont', 'Arial', sans-serif;
}

3. Images Not Loading

Problem: Images appear as broken in PDF

Solution: Use absolute URLs and ensure images load before PDF generation

<!-- Bad: Relative path -->
<img src="/images/logo.png">

<!-- Good: Absolute URL -->
<img src="https://yoursite.com/images/logo.png">

<!-- Better: Base64 embedded -->
<img src="data:image/png;base64,iVBORw0KG...">

4. CSS Not Applied

Problem: Styles don't render in PDF

Solution: Use inline styles or embedded <style> tags

<!-- External stylesheets may not load -->
<link rel="stylesheet" href="/styles.css">

<!-- Embed styles directly -->
<style>
    body { font-family: Arial; }
    .header { background: #4F46E5; }
</style>

5. Slow Generation

Problem: Each PDF takes 3-5 seconds to generate

Solution: Use native engines for simple documents

// Slow: Always use Chromium (1-3s)
const pdf = await page.pdf();

// Fast: Use native engine for invoices (<100ms)
const pdf = await lightningpdf.generate({
    template: 'invoice',
    engine: 'native' // Sub-100ms for simple layouts
});

Code Examples

Puppeteer (Node.js)

const puppeteer = require('puppeteer');

async function generatePDF(html) {
    const browser = await puppeteer.launch({
        headless: true,
        args: ['--no-sandbox']
    });

    const page = await browser.newPage();
    await page.setContent(html, { waitUntil: 'networkidle0' });

    const pdf = await page.pdf({
        format: 'A4',
        printBackground: true,
        margin: { top: '20px', right: '20px', bottom: '20px', left: '20px' }
    });

    await browser.close();
    return pdf;
}

// Usage
const html = '<h1>Hello PDF</h1>';
const pdf = await generatePDF(html);

Performance: 2-3 seconds, 200MB memory

wkhtmltopdf (Shell)

# Install
apt-get install wkhtmltopdf

# Generate PDF
wkhtmltopdf \
    --page-size A4 \
    --margin-top 20mm \
    input.html output.pdf

Performance: 500ms-1s, 50MB memory

LightningPDF (Any Language)

# cURL
curl https://lightningpdf.dev/api/v1/pdf/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"html": "<h1>Hello PDF</h1>"}' \
  -o output.pdf

// JavaScript
const response = await fetch('https://lightningpdf.dev/api/v1/pdf/generate', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({ html: '<h1>Hello PDF</h1>' })
});
const pdf = await response.buffer();

# Python
import requests

response = requests.post(
    'https://lightningpdf.dev/api/v1/pdf/generate',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={'html': '<h1>Hello PDF</h1>'}
)
pdf = response.content

Performance: <100ms for simple HTML (native engine), 10 lines of code

Advanced Techniques

Headers and Footers

<style>
    @page {
        margin: 2cm;
        @top-center {
            content: "Company Report";
        }
        @bottom-right {
            content: "Page " counter(page) " of " counter(pages);
        }
    }
</style>

Conditional Page Breaks

/* Keep tables together */
table {
    page-break-inside: avoid;
}

/* Start chapters on new page */
.chapter {
    page-break-before: always;
}

/* Prevent lonely headings */
h2, h3 {
    page-break-after: avoid;
}

Responsive Print Layouts

@media print {
    /* Hide navigation in PDFs */
    nav { display: none; }

    /* Adjust colors for print */
    body { color: #000; background: #fff; }

    /* Show URLs for links */
    a:after { content: " (" attr(href) ")"; }
}

Performance Optimization

1. Minimize HTML Size

// Bad: Lots of unused CSS
<link rel="stylesheet" href="bootstrap.min.css">

// Good: Only styles you need
<style>
    .invoice { font-family: Arial; }
</style>

2. Preload Images

// Wait for images to load before generating PDF
await page.evaluate(() => {
    return Promise.all(
        Array.from(document.images)
            .map(img => img.complete ? Promise.resolve() :
                new Promise(resolve => { img.onload = resolve; }))
    );
});

3. Reuse Browser Instances

// Bad: Launch new browser for each PDF (slow)
for (const html of documents) {
    const browser = await puppeteer.launch();
    await generatePDF(browser, html);
    await browser.close(); // 3s overhead per PDF
}

// Good: Reuse browser (fast)
const browser = await puppeteer.launch();
for (const html of documents) {
    await generatePDF(browser, html);
}
await browser.close();

4. Use Native Engines for Simple Documents

// Slow: Chromium for everything (1-3s each)
const invoicePDF = await chromium.generate(invoiceHTML);
const receiptPDF = await chromium.generate(receiptHTML);

// Fast: Native engine for simple docs (<100ms each)
const invoicePDF = await native.generate(invoiceHTML);   // 80ms
const receiptPDF = await native.generate(receiptHTML);   // 75ms

Choosing the Right Solution

Use Puppeteer/Playwright if you:

Need exact browser rendering
Already have infrastructure
Generate <100 PDFs/day
Have JavaScript-heavy content
Need full control over rendering

Use wkhtmltopdf if you:

Need simple, fast conversion
Don't require modern CSS
Have static content
Want free, open-source solution
Can tolerate rendering differences

Use PrinceXML if you:

Need advanced print features (running headers, footnotes)
Generate professional publications (books, magazines)
Require PDF/A compliance
Have budget for commercial license

Use LightningPDF if you:

Generate invoices, receipts, reports at scale
Want sub-100ms generation
Need template marketplace
Want batch processing (1000s of PDFs per call)
Prefer managed service over self-hosting
Need predictable $0.01/doc pricing

Real-World Use Case: E-commerce Invoices

Requirement: Generate 10,000 invoices/month

Option 1: Puppeteer (Self-Hosted)

Cost: $300/month infrastructure + 40 hours setup
Time: 2s × 10,000 = 5.5 hours/month
Code: 500+ lines (API, queue, storage, scaling)
Maintenance: 5 hours/month

Option 2: LightningPDF

Cost: $29/month (Pro plan)
Time: 0.08s × 10,000 = 13 minutes/month
Code: 10 lines
Maintenance: 0 hours (managed service)

Winner: LightningPDF saves $270/month and 45 hours/month while being 25x faster.

Security Considerations

Input Sanitization

// Sanitize user-provided HTML
const sanitizeHTML = require('sanitize-html');

const cleanHTML = sanitizeHTML(userHTML, {
    allowedTags: ['h1', 'h2', 'p', 'strong', 'em', 'table'],
    allowedAttributes: { 'td': ['colspan'], 'th': ['colspan'] }
});

const pdf = await generatePDF(cleanHTML);

Resource Limits

// Prevent malicious HTML from consuming resources
await page.setContent(html, {
    timeout: 5000, // 5s max
    waitUntil: 'domcontentloaded' // Don't wait for everything
});

Sandboxing

// Run Chromium in sandbox mode
const browser = await puppeteer.launch({
    args: [
        '--no-sandbox',
        '--disable-setuid-sandbox',
        '--disable-dev-shm-usage'
    ]
});

Testing Your PDFs

Visual Regression Testing

const { toMatchImageSnapshot } = require('jest-image-snapshot');
expect.extend({ toMatchImageSnapshot });

test('invoice renders correctly', async () => {
    const pdf = await generatePDF(invoiceHTML);
    const image = await convertPDFToImage(pdf);
    expect(image).toMatchImageSnapshot();
});

Content Validation

const pdfParse = require('pdf-parse');

test('invoice contains correct data', async () => {
    const pdf = await generateInvoice({ total: 1000 });
    const data = await pdfParse(pdf);
    expect(data.text).toContain('$1,000.00');
    expect(data.text).toContain('Invoice #');
});

Conclusion

HTML-to-PDF conversion in 2026 offers multiple approaches:

Browser-based (Puppeteer): Best for complex layouts, JavaScript-heavy content
Library-based (wkhtmltopdf): Good for simple, static content
API-based (LightningPDF): Best for production apps wanting speed, templates, and zero maintenance

For 95% of modern applications, an API like LightningPDF is the right choice:

10-25x faster than DIY
Template marketplace (save 10+ hours per template)
Batch processing
Zero infrastructure management
Predictable $0.01/doc pricing

Ready to start? Try LightningPDF free — 50 PDFs/month, full template marketplace, no credit card required.

Frequently Asked Questions

What is the best way to convert HTML to PDF?

For most production applications, a managed API like LightningPDF is the best way to convert HTML to PDF. It offers sub-100ms generation for simple documents, full CSS support including flexbox and grid, zero infrastructure management, and predictable per-document pricing starting at $0.003 each.

Is Puppeteer good for HTML to PDF conversion?

Puppeteer provides excellent CSS support since it uses real Chrome rendering, but it is slow at 1 to 3 seconds per PDF, requires significant infrastructure with 100 to 300 megabytes of memory per instance, and needs ongoing maintenance. It works well for low-volume use cases under 100 PDFs per day but becomes expensive to scale.

How do I fix page breaks in HTML to PDF?

Use CSS properties like break-inside avoid on table rows and cards, break-after avoid on headings, and set orphans and widows to 3 on paragraphs. LightningPDF also offers an automatic page-break-mode that handles these issues without manual CSS, including repeating table headers across pages.

How fast can HTML be converted to PDF?

Speed varies dramatically by approach. LightningPDF's native engine converts HTML to PDF in under 100 milliseconds for structured documents like invoices. Browser-based tools like Puppeteer take 1 to 3 seconds, wkhtmltopdf takes 500 milliseconds to 1 second, and PrinceXML takes 1 to 2 seconds per document.

Do I need a headless browser to convert HTML to PDF?

No, you do not need a headless browser. LightningPDF's native Go engine converts HTML to PDF without any browser, achieving sub-100ms speeds. For complex layouts requiring full browser rendering, the API handles Chromium internally so you never need to manage browser instances yourself.

Additional Resources

How to Fix PDF Page Breaks in HTML (The Complete Guide)

Digital Troubadour — Sat, 28 Feb 2026 08:25:08 +0000

How to Fix PDF Page Breaks in HTML

Page breaks are the #1 developer complaint about HTML-to-PDF conversion. Tables get cut mid-row, headings appear at the bottom of pages with no content following them, and images get sliced in half.

PDF page breaks are the points where content splits across pages during HTML-to-PDF conversion, often causing tables, images, and text blocks to be cut awkwardly unless controlled with CSS properties or smart rendering engines.

Here's how to fix every common page break problem.

The CSS Properties You Need

/* Prevent elements from being split across pages */
tr, .card, .item, figure, blockquote {
  break-inside: avoid;
  page-break-inside: avoid; /* Legacy support */
}

/* Keep headings with the content that follows */
h1, h2, h3 {
  break-after: avoid;
  page-break-after: avoid;
}

/* Repeat table headers on every page */
thead {
  display: table-header-group;
}

/* Control orphans and widows */
p, li {
  orphans: 3;
  widows: 3;
}

/* Force a page break before an element */
.page-break {
  break-before: page;
  page-break-before: always;
}

The Problem with Most PDF Generators

Most HTML-to-PDF tools (wkhtmltopdf, Puppeteer, headless Chrome) rely entirely on the browser's CSS page break implementation. This works okay for simple documents but fails for:

Tables: Rows get cut in half. Headers don't repeat.
Cards/Grids: Flexbox and grid items split unpredictably.
Images: Large images get cropped at page boundaries.

LightningPDF's Smart Page Breaks

LightningPDF solves this with a page_break_mode option:

{
  "html": "<table>...</table>",
  "options": {
    "page_break_mode": "auto"
  }
}

Modes

Mode	Behavior
`auto`	Smart page breaks: avoids splitting rows, repeats headers, respects CSS
`css`	Only respects your CSS break rules
`none`	No special page break handling

What "auto" mode does:

Adds break-inside: avoid to all table rows, cards, and block elements
Forces display: table-header-group on <thead> elements
Prevents breaks after headings
Sets orphan/widow minimums to 3 lines
Runs a JavaScript pre-render pass to detect elements that would be split

The Native Engine Advantage

For structured documents (invoices, receipts, reports), LightningPDF's native Go engine handles page breaks perfectly because it controls the layout directly:

Tables automatically split between rows (never mid-row)
Headers repeat on every page
Content height is pre-calculated before rendering

This is why native engine PDFs generate in under 100ms — no browser rendering needed.

Quick Fix Checklist

Add break-inside: avoid to table rows and card elements
Add break-after: avoid to headings
Set display: table-header-group on <thead>
Set orphans: 3; widows: 3 on paragraphs
Use LightningPDF's page_break_mode: "auto" for automatic handling

Try It Free

Frequently Asked Questions

Why do my PDF tables get cut in the middle of rows?

Tables get cut mid-row because most HTML-to-PDF tools rely on the browser's basic page break algorithm, which does not understand table row boundaries. Fix this by adding CSS break-inside avoid to table rows, or use LightningPDF's automatic page-break-mode which prevents mid-row splits and repeats headers on every page.

What CSS properties control PDF page breaks?

The key CSS properties for PDF page breaks are break-inside avoid to prevent elements from splitting, break-before page to force a new page, break-after avoid to keep headings with their content, and orphans and widows set to 3 to prevent lonely lines. The legacy page-break prefix versions work in older tools.

How do I repeat table headers on every PDF page?

Add the CSS rule display table-header-group to your thead element. This tells the PDF renderer to repeat the table header row at the top of each page when a table spans multiple pages. LightningPDF's auto mode applies this rule automatically.

Does LightningPDF handle page breaks automatically?

Yes, LightningPDF offers a page-break-mode auto setting that automatically prevents mid-row table splits, repeats table headers, keeps headings with following content, and sets minimum orphan and widow lines. The native Go engine handles page breaks perfectly for structured documents like invoices and reports.

Most webhook tutorials focus on getting things working. Parse the JSON, handle the event, return 200. But a webhook endpoint in production is an attack surface. Without proper security, it's an open door.

Digital Troubadour — Thu, 26 Feb 2026 06:22:59 +0000

Webhook Security Best Practices for Production 2025-2026

Digital Troubadour ・ Feb 26

#webdev #programming #devops #security

Webhook Security Best Practices for Production 2025-2026

Digital Troubadour — Thu, 26 Feb 2026 06:14:07 +0000

Webhook Security Best Practices for Production

A webhook endpoint is a publicly accessible URL that accepts arbitrary POST requests from the internet. Read that sentence again. If that doesn't make you a little nervous, it should.

Most webhook tutorials focus on getting things working. Parse the JSON, handle the event, return 200. But a webhook endpoint in production is an attack surface. Without proper security, it's an open door.

Verify Signatures. Every Time.

This is the single most important thing. Every major webhook provider signs their payloads — Stripe, GitHub, Shopify, Twilio, Slack. The signature proves the request actually came from them and wasn't tampered with in transit.

The pattern is always the same: the provider computes an HMAC of the request body using a shared secret, sends the signature in a header, and you recompute the HMAC on your end and compare.

Skip this and anyone can POST fake events to your endpoint. A forged payment_intent.succeeded event could grant access to someone who never paid. A forged customer.subscription.deleted could revoke a paying customer's access.

func verifyStripeSignature(payload []byte, sigHeader string, secret string) error {
    return stripe.VerifySignature(payload, sigHeader, secret)
}

func verifyGitHubSignature(payload []byte, sigHeader string, secret string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(payload)
    expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(expected), []byte(sigHeader))
}

Two things people get wrong:

Comparing signatures with == instead of constant-time comparison. Regular string equality short-circuits — it returns false as soon as it finds a mismatched character. An attacker can time the responses to figure out the signature byte by byte. Use hmac.Equal (Go), crypto.timingSafeEqual (Node), or hmac.compare_digest (Python).

Parsing the body before verifying the signature. The signature is computed against the raw bytes. If your web framework parses JSON before your middleware runs, the reparsed output might have different whitespace or key ordering. Always read the raw body first, verify, then parse. In Express this means express.raw() on the webhook route. In Django, use request.body not request.data.

Prevent SSRF Attacks

Here's a scenario that bit us when we were building ThunderHooks.

You build a webhook replay feature. User provides a URL, your server sends an HTTP request to it. Seems straightforward. But what if the user enters http://169.254.169.254/latest/meta-data/? That's the AWS metadata endpoint. Your server just fetched IAM credentials and returned them to the user.

Or http://localhost:6379/ — now they're talking to your Redis instance. Or http://10.0.0.5:5432/ — your internal Postgres. Any feature where your server makes HTTP requests to user-provided URLs is a potential SSRF (Server-Side Request Forgery) vector.

This applies to:

Webhook replay (user provides target URL)
Webhook relay destinations
Custom webhook verification callbacks
OAuth redirect URLs

How to Prevent It

Block requests to private IP ranges at the network level. Don't just check the hostname — resolve it first, then check the IP.

func isSafeURL(targetURL string) error {
    parsed, err := url.Parse(targetURL)
    if err != nil {
        return fmt.Errorf("invalid URL")
    }

    // Must be HTTPS (or HTTP for local dev)
    if parsed.Scheme != "https" && parsed.Scheme != "http" {
        return fmt.Errorf("unsupported scheme: %s", parsed.Scheme)
    }

    // Resolve hostname to IP
    ips, err := net.LookupIP(parsed.Hostname())
    if err != nil {
        return fmt.Errorf("DNS resolution failed")
    }

    for _, ip := range ips {
        if ip.IsLoopback() || ip.IsPrivate() || ip.IsLinkLocalUnicast() {
            return fmt.Errorf("target resolves to private IP")
        }
    }

    return nil
}

But this has a race condition. DNS can return a different IP between your check and the actual HTTP request (a technique called DNS rebinding). The proper fix is validating at the transport level — during the TCP dial, not before it.

transport := &http.Transport{
    DialContext: func(ctx context.Context, network, addr string) (net.Conn, error) {
        host, port, _ := net.SplitHostPort(addr)
        ips, err := net.DefaultResolver.LookupIPAddr(ctx, host)
        if err != nil {
            return nil, err
        }

        for _, ip := range ips {
            if ip.IP.IsLoopback() || ip.IP.IsPrivate() || ip.IP.IsLinkLocalUnicast() {
                return nil, fmt.Errorf("blocked: %s resolves to %s", host, ip.IP)
            }
        }

        // Dial with the resolved IP, not the hostname
        dialer := &net.Dialer{Timeout: 10 * time.Second}
        return dialer.DialContext(ctx, network, addr)
    },
}

client := &http.Client{Transport: transport}

This is the approach ThunderHooks uses. Every outgoing request — replays, relays, monitor checks — goes through a transport that validates the destination IP at dial time. No TOCTOU race, no DNS rebinding.

Rate Limit Your Endpoint

Even with signature verification, your endpoint should have rate limits. Why?

Replay attacks. A valid signed request intercepted in transit can be resent repeatedly. Rate limiting bounds the damage.
Accidental loops. A misconfigured webhook that triggers itself can generate thousands of requests per minute.
Provider retries during outages. If your handler returns 500 during a deploy, the webhook provider starts retrying. Combined with normal traffic, this can overwhelm your server during recovery.

A simple approach using a token bucket or sliding window per source IP:

from flask_limiter import Limiter

limiter = Limiter(app, key_func=get_remote_address)

@app.route('/webhooks/stripe', methods=['POST'])
@limiter.limit("60/minute")
def stripe_webhook():
    # ...

Be careful with the limit. Stripe can send bursts during batch operations — a subscription migration might fire hundreds of events in seconds. Set the limit high enough for legitimate spikes but low enough to catch abuse. Start with 100/minute and adjust based on your actual traffic patterns.

Validate Payload Structure

Don't trust the payload blindly just because the signature is valid. Signatures prove authenticity, not correctness.

app.post('/webhooks/stripe', (req, res) => {
  const event = JSON.parse(req.body);

  // Don't do this
  const amount = event.data.object.amount;
  await db.query('UPDATE orders SET amount = $1 WHERE id = $2', [amount, event.data.object.metadata.order_id]);
});

What if event.data.object.metadata.order_id contains '; DROP TABLE orders; --? The signature is valid — Stripe really sent that payload — but the metadata came from user input on your checkout page.

Validate and sanitize:

app.post('/webhooks/stripe', (req, res) => {
  const event = JSON.parse(req.body);

  if (event.type !== 'payment_intent.succeeded') {
    return res.status(200).end();
  }

  const orderId = event.data.object.metadata?.order_id;
  if (!orderId || typeof orderId !== 'string' || orderId.length > 64) {
    console.error('Invalid order_id in webhook metadata');
    return res.status(200).end(); // Don't retry
  }

  // Use parameterized queries (always)
  await db.query('UPDATE orders SET paid = true WHERE id = $1', [orderId]);
});

Parameterized queries protect against SQL injection regardless, but validating the shape of the data catches bugs early and makes your handler more predictable.

Enforce HTTPS

Webhook payloads contain sensitive data — payment amounts, customer emails, API keys in headers. Sending this over plain HTTP means anyone on the network path can read it.

Every serious webhook provider requires HTTPS endpoints. Stripe flat-out rejects HTTP URLs. GitHub warns you but technically allows it.

In production, there's no reason to accept webhook traffic over HTTP. If you're running behind a load balancer or reverse proxy that terminates TLS:

server {
    listen 80;
    server_name api.yourapp.com;

    # Redirect everything to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    server_name api.yourapp.com;

    ssl_certificate /etc/letsencrypt/live/api.yourapp.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.yourapp.com/privkey.pem;

    location /webhooks/ {
        proxy_pass http://localhost:3000;
    }
}

Monitor your certificate expiry. An expired cert means webhook providers get TLS errors and your integrations silently break. Let's Encrypt certs expire every 90 days — make sure auto-renewal is working and alerting if it fails.

Limit Payload Size

A webhook endpoint that accepts arbitrarily large payloads is asking for trouble. An attacker (or a buggy provider) could send a multi-gigabyte request body and exhaust your server's memory.

Set a reasonable maximum. Most webhook payloads are under 100KB. Stripe's largest payloads (for events like invoice.finalized with many line items) rarely exceed 500KB.

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    // Limit to 1MB
    r.Body = http.MaxBytesReader(w, r.Body, 1<<20)

    payload, err := io.ReadAll(r.Body)
    if err != nil {
        http.Error(w, "payload too large", http.StatusRequestEntityTooLarge)
        return
    }

    // proceed...
}

In Express:

app.post('/webhooks/stripe',
  express.raw({ type: 'application/json', limit: '1mb' }),
  handler
);

Timestamp Validation

Stripe includes a timestamp in the signature header (t=1234567890). You should verify this timestamp is recent — within five minutes, say.

Why? Without timestamp validation, an attacker who captures a valid signed request can replay it hours, days, or weeks later. The signature is still valid because the secret hasn't changed. But the timestamp check catches it.

func verifyStripeTimestamp(sigHeader string) error {
    // Parse timestamp from "t=123,v1=abc..." format
    parts := strings.Split(sigHeader, ",")
    var timestamp int64
    for _, part := range parts {
        if strings.HasPrefix(part, "t=") {
            ts, err := strconv.ParseInt(strings.TrimPrefix(part, "t="), 10, 64)
            if err != nil {
                return fmt.Errorf("invalid timestamp")
            }
            timestamp = ts
        }
    }

    tolerance := int64(300) // 5 minutes
    now := time.Now().Unix()
    if now - timestamp > tolerance {
        return fmt.Errorf("timestamp too old: %d seconds", now - timestamp)
    }

    return nil
}

Stripe's official libraries do this automatically if you use stripe.webhooks.constructEvent(). Don't skip it by rolling your own verification without the timestamp check.

Log Everything, Expose Nothing

Log every incoming webhook — event type, delivery ID, timestamp, processing result, and any errors. You'll need this when debugging "why didn't we process that payment?"

But be careful what you log. Webhook payloads can contain PII (names, emails, addresses) and sensitive financial data (payment amounts, card last four digits). Your logging strategy needs to account for this.

log.Info("webhook received",
    "event_type", event.Type,
    "event_id", event.ID,
    "delivery_id", r.Header.Get("X-GitHub-Delivery"),
    // DON'T log the full payload in production
    // "payload", string(payload),
)

In development, log everything. In production, log metadata (event type, IDs, timestamps) but not the full payload. If you need to inspect production payloads for debugging, use a secure audit log with access controls — not stdout that goes to a shared Datadog instance everyone can query.

Security Checklist

For every webhook endpoint going to production:

[ ] Signature verification with constant-time comparison
[ ] Raw body access before JSON parsing
[ ] SSRF protection on any outbound requests (replay, relay)
[ ] Rate limiting per source IP
[ ] Payload size limit (1MB is a safe default)
[ ] Timestamp validation (Stripe) or equivalent replay protection
[ ] HTTPS only, with certificate monitoring
[ ] Input validation on user-controlled fields within payloads
[ ] Parameterized queries for any database operations
[ ] Structured logging without PII in production
[ ] Idempotency keys to handle duplicate deliveries

None of these are difficult individually. The danger is skipping them during the "just get it working" phase and never going back.

Resources

Testing webhooks during local development is one of those problems that sounds simple until you actually try to do it. Your localhost isn't accessible from the internet, so services like Stripe, GitHub, or Shopify can't reach your development server.

Digital Troubadour — Thu, 26 Feb 2026 06:08:53 +0000

How to Test Webhooks Locally: Complete 2026 Guide

Digital Troubadour ・ Feb 26

#api #testing #tutorial #webdev

How to Test Webhooks Locally: Complete 2026 Guide

Digital Troubadour — Thu, 26 Feb 2026 06:07:55 +0000

How to Test Webhooks Locally

Testing webhooks during local development is one of those problems that sounds simple until you actually try to do it. Your localhost isn't accessible from the internet, so services like Stripe, GitHub, or Shopify can't reach your development server.

Here's the thing: there are several ways to solve this, and the right choice depends on your situation.

The Core Problem

When Stripe wants to notify you about a successful payment, it sends an HTTP POST request to your webhook URL. In production, that's straightforward—your server has a public URL.

But during development? Your app is running on localhost:3000. Stripe can't reach that. Neither can any other webhook provider.

Solution 1: Tunneling Tools

The most common approach is creating a tunnel from the public internet to your local machine.

ngrok

ngrok is the go-to tool for this. Install it, run ngrok http 3000, and you get a public URL like https://abc123.ngrok.io that forwards to your local server.

ngrok http 3000

The free tier works, but URLs change every time you restart. That means updating your webhook configuration in Stripe/GitHub/wherever constantly. The paid tiers ($8-25/month) give you stable URLs.

Cloudflare Tunnel

If you're already using Cloudflare, their Tunnel product (formerly Argo Tunnel) is solid. It's free and integrates with your existing Cloudflare setup.

cloudflared tunnel --url http://localhost:3000

localtunnel

localtunnel is an open source alternative. Simple to use, but reliability can be hit or miss:

npx localtunnel --port 3000

Solution 2: Webhook Capture Services

Instead of tunneling, you can use a service that captures webhooks for you to inspect and replay. Think of it as an inbox for your webhooks.

This solves problems that tunneling can't:

Webhooks arrive at 3am? Captured and waiting in your dashboard. Your laptop can be closed.
Need to replay the same webhook 20 times while debugging? No problem. No need to trigger real events in Stripe repeatedly.
Tired of updating webhook URLs every time ngrok restarts? Set the URL once, never touch it again.
Want to see exactly what Stripe sends before writing code? Inspect headers, body, and timing first.

How it works

You get a permanent URL (e.g., https://thunderhooks.com/h/my-project)
Configure Stripe/GitHub/etc. to send webhooks there—once, and forget it
Webhooks are captured and stored (typically 7-30 days)
When you're ready to code, open the dashboard and inspect the payload
Start a tunnel, then replay the webhook to your tunnel URL
Bug in your code? Fix it and replay the same webhook again

Why this beats tunneling alone

With ngrok, you need the tunnel running when the webhook arrives. Miss it and it's gone—you have to trigger another real event.

With a capture service, webhooks queue up like emails. Process them when you're ready. Replay them as many times as needed. Your development workflow isn't tied to keeping a tunnel alive 24/7.

The tradeoff: it's a two-step process (capture → replay) instead of direct forwarding. But for most webhook development, that tradeoff is worth it.

Solution 3: Provider-Specific Tools

Some webhook providers have their own testing tools.

Stripe CLI

Stripe's CLI can forward webhook events to your local server:

stripe listen --forward-to localhost:3000/webhooks/stripe

It also lets you trigger test events:

stripe trigger payment_intent.succeeded

This is excellent for Stripe-specific development. The limitation is obvious—it only works for Stripe.

GitHub CLI

GitHub doesn't have webhook forwarding built-in, but you can use their API to redeliver webhooks from the settings page.

Practical Workflow

Here's what actually works well day-to-day:

For quick debugging: Use a capture service. See what's being sent, inspect headers and payloads, then replay to your local server.

For integration testing: Use the Stripe CLI (or equivalent) to trigger specific events and verify your handling code.

For end-to-end testing: Set up a tunnel with a stable URL so real webhook events flow through during testing.

Common Mistakes

Not verifying signatures: In development, it's tempting to skip signature verification. Don't. You'll forget to enable it in production. See Stripe's signature verification docs for implementation details.

Hardcoding URLs: Store webhook URLs in environment variables. Your local, staging, and production environments need different URLs.

Ignoring idempotency: Webhooks can be delivered multiple times. Your handler needs to handle duplicates gracefully. Test this by replaying the same webhook twice.

Missing timeout handling: Webhook providers expect quick responses (usually under 30 seconds). If your handler does heavy processing, return 200 immediately and process asynchronously.

Testing Checklist

Before deploying webhook handlers to production:

[ ] Handler returns 2xx status quickly
[ ] Signature verification is enabled
[ ] Duplicate deliveries are handled (idempotency)
[ ] Failures are logged with enough context to debug
[ ] Retry logic handles temporary failures
[ ] Timeout handling works correctly

Conclusion

The webhook testing landscape has improved a lot. Between tunneling tools, capture services, and provider-specific CLIs, you have options.

Pick the approach that fits your workflow. For most teams, a combination works best: capture services for debugging and inspection, provider CLIs for triggering test events, and tunnels for full integration testing.

Resources

[Boost]

Digital Troubadour — Thu, 19 Feb 2026 18:51:23 +0000

10 Best ngrok Alternatives for Webhook Testing (2026) - DEV Community

10 Best ngrok Alternatives for Webhook Testing ngrok is the default recommendation for...

dev.to

10 Best ngrok Alternatives for Webhook Testing (2026)

Digital Troubadour — Thu, 19 Feb 2026 18:49:55 +0000

10 Best ngrok Alternatives for Webhook Testing

ngrok is the default recommendation for exposing localhost to the internet. It works, it's well-documented, and the free tier is functional.

But it's not the only option, and depending on your needs, it might not be the best one.

Why Look for Alternatives?

A few common pain points with ngrok:

Free tier URLs change every restart. Annoying when you're constantly updating webhook configs.
Pricing jumps from free to $8/month for basic features, $20/month for custom domains.
Rate limits on the free tier can interrupt development.
No request history unless you pay. Debugging is harder without seeing what was sent.

Let's look at what else is out there.

1. Cloudflare Tunnel (Free)

If you already use Cloudflare, this is a no-brainer. Cloudflare Tunnel (formerly Argo Tunnel) is free and well-maintained.

cloudflared tunnel --url http://localhost:3000

Pros:

Free with no artificial limits
Backed by Cloudflare's infrastructure
Can connect to your own domain

Cons:

Requires Cloudflare account
Setup is more involved than ngrok
No built-in request inspection

Best for: Teams already using Cloudflare.

Get started with Cloudflare Tunnel

2. localhost.run (Free)

Dead simple. No installation required—just SSH. Check out localhost.run.

ssh -R 80:localhost:3000 nokey@localhost.run

Pros:

No signup, no installation
Works anywhere with SSH

Cons:

URLs change on reconnect
Limited features
Reliability varies

Best for: Quick one-off testing when you don't want to install anything.

localhost.run documentation

3. Tailscale Funnel (Free)

Tailscale's Funnel feature exposes local services to the internet through their network.

tailscale funnel 3000

Pros:

Free tier is generous
Integrates with Tailscale VPN
Stable URLs with your Tailscale domain

Cons:

Requires Tailscale setup
Overkill if you only need tunneling

Best for: Teams already using Tailscale for networking.

Tailscale Funnel examples

4. localtunnel (Free, Open Source)

localtunnel is open source and npm-installable.

npx localtunnel --port 3000

Pros:

Free and open source
Easy to use
Can request specific subdomain

Cons:

Reliability issues (shared infrastructure)
URLs can be slow to connect
No request logging

Best for: Quick tests when reliability isn't critical.

localtunnel on npm

5. Expose (Self-Hosted)

Expose is a PHP-based tunnel server you can self-host.

Pros:

Self-hosted = full control
Free (you pay for hosting)
Custom domains

Cons:

Requires server setup
PHP dependency
Maintenance overhead

Best for: Teams with ops capacity who want full control.

6. bore (Open Source)

bore is a minimal Rust-based tunnel. Fast and simple.

bore local 3000 --to bore.pub

Pros:

Lightweight and fast
Open source
Can self-host the server

Cons:

Fewer features than ngrok
Smaller community

Best for: Developers who want something minimal.

7. Pagekite (Paid, Self-Hostable)

Pagekite has been around longer than ngrok. Reliable and battle-tested.

Pros:

Stable and mature
Self-hosting option
Pay-what-you-want pricing

Cons:

Interface feels dated
Less popular means fewer resources

Best for: Long-running tunnels where stability matters.

8. Telebit (Free, Open Source)

Telebit is a Node.js-based tunnel with Let's Encrypt integration.

Pros:

Free and open source
Automatic HTTPS
Can self-host

Cons:

Smaller community
Documentation could be better

Best for: Node.js developers comfortable with self-hosting.

9. Webhook Capture Services (Different Approach)

This is a fundamentally different approach. Instead of tunneling traffic in real-time, services like ThunderHooks capture webhooks and store them for later inspection and replay.

The workflow:

Stripe → ThunderHooks (captures & stores) → You inspect when ready → Replay to your tunnel

Why developers switch to this:

Your laptop can be closed. Webhook arrives at 3am? It's waiting in your dashboard tomorrow.
Set the URL once, forever. No more updating Stripe/GitHub every time ngrok restarts. Configure thunderhooks.com/h/my-project and forget it.
Replay the same webhook 50 times. Debugging a tricky handler? Replay until it works. No need to trigger real Stripe payments repeatedly.
See what's coming before you code. Inspect the exact headers and payload Stripe sends before writing your handler.
30-day history. "What did that webhook look like last week?" You can find out.

Pros:

Permanent URLs that never change
Full request history with headers, body, timing
Replay and edit payloads before sending
Works offline—webhooks queue up like email
Debug production issues by capturing real traffic

Cons:

Two-step process (capture → replay) instead of direct forwarding
Need a tunnel running when you replay (but not 24/7)

Best for: Teams tired of babysitting tunnels. Debugging webhook handlers. Inspecting payloads before coding. Testing edge cases by editing payloads.

10. Provider-Specific CLIs

Stripe, Twilio, and other providers have their own CLI tools with webhook forwarding.

stripe listen --forward-to localhost:3000/webhooks/stripe

Pros:

Deep integration with the provider
Can trigger test events
Handles signature verification

Cons:

Only works for that specific provider
Need multiple tools for multiple providers

Best for: Development focused on a single provider.

Stripe CLI documentation

Comparison Table

Tool	Free Tier	Stable URLs	Request History	Self-Host
ngrok	Yes (limited)	Paid only	Paid only	No
Cloudflare Tunnel	Yes	Yes	No	No
localhost.run	Yes	No	No	No
Tailscale Funnel	Yes	Yes	No	No
localtunnel	Yes	Partial	No	Yes
bore	Yes	No	No	Yes
Webhook capture	Varies	Yes	Yes	Some

Which Should You Choose?

Already using Cloudflare? Use Cloudflare Tunnel.

Already using Tailscale? Use Tailscale Funnel.

Need to inspect payloads and debug? Use a webhook capture service.

Just need a quick tunnel? localhost.run or localtunnel.

Want full control? Self-host bore or Expose.

Working with Stripe specifically? Stripe CLI.

There's no single best answer. The right tool depends on what you're building and how you work. Most teams end up using a combination—tunneling for real-time testing, capture services for debugging.

Forem: Digital Troubadour

Generating PDFs from HTML in Node.js (and why I stopped using Puppeteer)

What's actually wrong with Puppeteer

The other options people try

wkhtmltopdf

PDFKit / jsPDF

An API

What using an API actually looks like

Templates for documents you generate repeatedly

Batch generation

Rough performance numbers

Is this worth it for a small project?

[Boost]

HTML to PDF - The Complete Guide for 2026

Digital Troubadour ・ Mar 7

HTML to PDF - The Complete Guide for 2026

HTML to PDF: The Complete Guide for 2026

Why HTML to PDF?

The Three Approaches

1. Browser-Based (Headless Chrome/Chromium)

2. Library-Based (wkhtmltopdf, PrinceXML)

3. API-Based (Managed Services)

Comparison Table

Common Pitfalls and Solutions

1. Page Breaks

2. Missing Fonts

3. Images Not Loading

4. CSS Not Applied

5. Slow Generation

Code Examples

Puppeteer (Node.js)

wkhtmltopdf (Shell)

LightningPDF (Any Language)

Advanced Techniques

Headers and Footers

Conditional Page Breaks

Responsive Print Layouts

Performance Optimization

1. Minimize HTML Size

2. Preload Images

3. Reuse Browser Instances

4. Use Native Engines for Simple Documents

Choosing the Right Solution

Use Puppeteer/Playwright if you:

Use wkhtmltopdf if you:

Use PrinceXML if you:

Use LightningPDF if you:

Real-World Use Case: E-commerce Invoices

Option 1: Puppeteer (Self-Hosted)

Option 2: LightningPDF

Security Considerations

Input Sanitization

Resource Limits

Sandboxing

Testing Your PDFs

Visual Regression Testing

Content Validation

Conclusion

Frequently Asked Questions

What is the best way to convert HTML to PDF?

Is Puppeteer good for HTML to PDF conversion?

How do I fix page breaks in HTML to PDF?

How fast can HTML be converted to PDF?

Do I need a headless browser to convert HTML to PDF?

Related Reading

Additional Resources

How to Fix PDF Page Breaks in HTML (The Complete Guide)

How to Fix PDF Page Breaks in HTML

The CSS Properties You Need

The Problem with Most PDF Generators

LightningPDF's Smart Page Breaks

Modes

What "auto" mode does:

The Native Engine Advantage

Quick Fix Checklist

Try It Free

Frequently Asked Questions

Why do my PDF tables get cut in the middle of rows?

What CSS properties control PDF page breaks?

How do I repeat table headers on every PDF page?