DEV Community: Digital Troubadour

[Boost]

Digital Troubadour — Thu, 04 Jun 2026 15:36:04 +0000

Digital Troubadour

Jun 4

Stripe Webhook Testing: Local Development Guide

#webdev #productivity #automation #ai

5 min read

Stripe Webhook Testing: Local Development Guide

Digital Troubadour — Thu, 04 Jun 2026 15:33:53 +0000

Stripe webhooks notify your application about events—successful payments, failed charges, subscription changes, disputes. Getting them right matters. A missed webhook can mean unfulfilled orders or confused customers.

Testing webhooks locally used to be painful. Now Stripe has decent tooling. Here's how to use it effectively.

Setting Up the Stripe CLI

The Stripe CLI is your primary tool for local webhook testing. Install it first.

macOS:

brew install stripe/stripe-cli/stripe

Windows:

scoop install stripe

Linux:
Download from Stripe's releases page or use their apt/yum repos.

After installation, authenticate:

stripe login

This opens a browser to link your Stripe account. You'll need to redo this periodically—the session expires.

Forwarding Webhooks to Localhost

Start the listener:

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

You'll see output like:

Ready! Your webhook signing secret is whsec_abc123...

Save that signing secret. You'll need it for signature verification. It's different from your dashboard webhook secret—this one is specific to the CLI session.

Set it in your environment:

export STRIPE_WEBHOOK_SECRET=whsec_abc123...

Now Stripe CLI intercepts webhooks and forwards them to your local server.

Triggering Test Events

You can trigger specific events without making real payments:

stripe trigger payment_intent.succeeded

Common events to test:

# Payment flow
stripe trigger payment_intent.succeeded
stripe trigger payment_intent.payment_failed
stripe trigger charge.refunded

# Subscriptions
stripe trigger customer.subscription.created
stripe trigger customer.subscription.updated
stripe trigger customer.subscription.deleted
stripe trigger invoice.paid
stripe trigger invoice.payment_failed

# Checkout
stripe trigger checkout.session.completed

Each trigger sends a realistic webhook payload to your forwarded endpoint.

Signature Verification

Always verify webhook signatures. See Stripe's signature verification guide for full details. Here's the pattern in different languages:

Node.js:

const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

app.post('/webhooks/stripe', express.raw({type: 'application/json'}), (req, res) => {
  const sig = req.headers['stripe-signature'];

  let event;
  try {
    event = stripe.webhooks.constructEvent(
      req.body,
      sig,
      process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch (err) {
    console.log(`Webhook signature verification failed.`, err.message);
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  // Handle the event
  switch (event.type) {
    case 'payment_intent.succeeded':
      const paymentIntent = event.data.object;
      // Handle successful payment
      break;
    // ... other cases
  }

  res.json({received: true});
});

Go:

func handleWebhook(w http.ResponseWriter, r *http.Request) {
    payload, err := io.ReadAll(r.Body)
    if err != nil {
        http.Error(w, "Error reading body", http.StatusBadRequest)
        return
    }

    event, err := webhook.ConstructEvent(
        payload,
        r.Header.Get("Stripe-Signature"),
        os.Getenv("STRIPE_WEBHOOK_SECRET"),
    )
    if err != nil {
        http.Error(w, "Signature verification failed", http.StatusBadRequest)
        return
    }

    switch event.Type {
    case "payment_intent.succeeded":
        // Handle
    }

    w.WriteHeader(http.StatusOK)
}

Python:

import stripe
from flask import Flask, request

@app.route('/webhooks/stripe', methods=['POST'])
def stripe_webhook():
    payload = request.get_data()
    sig_header = request.headers.get('Stripe-Signature')

    try:
        event = stripe.Webhook.construct_event(
            payload, sig_header, os.environ['STRIPE_WEBHOOK_SECRET']
        )
    except ValueError as e:
        return 'Invalid payload', 400
    except stripe.error.SignatureVerificationError as e:
        return 'Invalid signature', 400

    if event['type'] == 'payment_intent.succeeded':
        payment_intent = event['data']['object']
        # Handle

    return '', 200

The Raw Body Problem

A common gotcha: signature verification requires the raw request body. If your framework parses JSON automatically before your handler runs, verification will fail.

In Express, use express.raw():

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

In other frameworks, ensure you're reading the raw body before any JSON parsing middleware touches it. The Stripe docs on signature errors cover this in detail.

Debugging Failed Webhooks

When things go wrong:

1. Check the CLI output

The Stripe CLI shows request/response details:

2026-01-25 10:23:45   --> payment_intent.succeeded [evt_123...]
2026-01-25 10:23:45   <-- [400] POST http://localhost:3000/webhooks/stripe

A 400 response usually means signature verification failed.

2. Check your logs

Add logging before and after signature verification to see where it fails.

3. Verify the secret

The CLI provides a session-specific secret. Make sure you're using the right one. The secret from your Stripe dashboard won't work with CLI-forwarded webhooks.

4. Check for body parsing issues

If you're getting "No signatures found matching the expected signature for payload" errors, you likely have a body parsing problem.

Testing Without the CLI

Sometimes you want to test with captured real payloads. Options:

Replay from Stripe Dashboard:
In your Stripe dashboard, go to Developers > Webhooks > your endpoint. You can resend any recent webhook delivery.

Use a webhook capture service:
Services like ThunderHooks act as a webhook inbox. Point Stripe at your ThunderHooks URL once, and every webhook is captured—even when your laptop is closed.

When you're ready to debug:

Open your dashboard, see the exact payload Stripe sent
Start ngrok or your preferred tunnel
Replay the webhook to your tunnel URL
Fix your bug, replay again—same webhook, no need to trigger another Stripe event

This is especially useful for debugging production issues. Capture real production webhooks, then replay them against your local code until you find the bug.

Mock the webhook:
For unit tests, don't call Stripe at all. Mock the webhook payload and test your handler logic directly.

Production Checklist

Before going live:

[ ] Webhook endpoint is HTTPS (required by Stripe)
[ ] Signature verification is enabled with production secret
[ ] Handler returns 2xx quickly (< 30 seconds)
[ ] Idempotency handling for duplicate deliveries
[ ] Error logging captures event ID for debugging
[ ] Retry handling for temporary failures
[ ] Critical events have monitoring/alerting

Common Events to Handle

At minimum, most Stripe integrations need:

Event	When	Action
`checkout.session.completed`	Customer finishes checkout	Fulfill order
`payment_intent.succeeded`	Payment completes	Record payment, send receipt
`payment_intent.payment_failed`	Payment fails	Notify customer, retry logic
`customer.subscription.created`	New subscription	Provision access
`customer.subscription.deleted`	Subscription canceled	Revoke access
`invoice.payment_failed`	Subscription payment fails	Dunning flow

See Stripe's webhook events documentation for the full list.

Conclusion

The Stripe CLI makes local webhook testing manageable. Set up forwarding, trigger events, verify signatures work, and test your handler logic.

The key is testing the unhappy paths too—failed payments, disputed charges, expired cards. Those are where webhook handling bugs tend to hide.

Resources

WordPress 7.0 Is Here. Will Your PDF Invoice Plugin Survive It?

Digital Troubadour — Thu, 21 May 2026 20:14:07 +0000

WordPress 7.0 landed on May 20, 2026. Most of it is plumbing you will never see. But if your store emails invoices, there is a real chance the update quietly changes what those invoices look like, and you will not find out until a customer replies asking why their receipt is full of empty boxes.

Whether that happens to you comes down to one thing: where your PDFs are actually rendered.

The part of 7.0 that matters to you

Skip the release notes. Three changes can touch a document plugin.

The biggest is that PHP 7.2 and 7.3 are gone. The supported floor is now PHP 7.4, with 8.3 recommended. If your host is still serving 7.2 or 7.3, code that ran fine last week can start throwing fatal errors the moment you update core, and PDF libraries that never modernized are prime candidates.

The other two are cosmetic until they aren't. The block editor keeps moving into an iframe, which trips up plugins that inject editor styles the old way. And the admin gets a new default theme called Modern, which will expose any plugin that hardcoded its own admin colors over the top of core.

There is also a new AI Client, a central API-key screen, and PHP-only block registration. All opt-in, none of it breaks anything. File those under "interesting later."

Server-side rendering is the thing that breaks

Open the settings page of almost any WooCommerce invoice plugin and you will find DOMPDF, mPDF, or TCPDF doing the work. They take your order, run it through a PHP library, and write a file on your server. It is a reasonable design until the ground moves under it, which is exactly what a major core release does.

Three things go wrong, and 7.0 nudges all of them.

A server-rendered PDF is welded to your PHP runtime. Move the version floor and a library that has not kept pace either spits deprecation warnings or dies outright. It is also welded to your live environment, so the output depends on which fonts the server has, what your theme is doing, and which libraries happen to be loaded when the render fires. Change any of those and the document drifts. And most of these engines were built for a web that predates CSS Grid. Flexbox has sat marked "unsupported" on their issue trackers for the better part of a decade. A new admin theme does not fix that. Nothing in core will.

So the plugins most likely to hand a customer a broken invoice after the upgrade are the ones rendering on the machine that just got upgraded. That is not bad luck. It is the architecture.

Why a cloud renderer shrugs this off

Paperbolt does not render anything on your site. WordPress makes one HTTPS call to the LightningPDF cloud, Chromium renders the document there, and the file comes back. That sounds like a small distinction. It is the whole game.

Your PHP version stops mattering, because the plugin's only job is to send a request. 7.4 or 8.3, the renderer never sees it. Core and theme updates stop mattering too, because the invoice is built from your template and your data on a different machine entirely. A new admin theme changes how WordPress looks in a browser tab. It does not change the bytes of a PDF that was rendered somewhere else.

The script support comes free with the same decision. Hindi, Bengali, Tamil, Hebrew, Arabic, Thai, and the CJK languages render the way they do in Chrome, because it is Chrome's engine, not a PHP font shim. Flexbox, Grid, and real webfonts work for the same reason. WordPress 7.0 neither adds nor removes a single character of that.

Update to 7.0 and the invoice you send tomorrow is byte-for-byte the one you sent yesterday. There is nothing on your server for the upgrade to disturb.

Is Paperbolt compatible with WordPress 7.0?

Yes, and version 1.1.1 says so in the header. The download block uses the standard block-editor APIs with a server-side render callback, so the iframe move does not reach it. The settings screen scopes its styles to its own page and never touches core admin chrome, so the Modern theme has nothing to fight with. And Paperbolt already required PHP 7.4, so the dropped versions were never in play.

If you run a different plugin, upgrade in this order

Check your PHP version before you touch anything else. Sitting on 7.2 or 7.3 means moving to 7.4 or higher first, which most hosts let you do from the control panel in two clicks. Then stage the update with the WordPress Beta Tester plugin instead of betting your live store on it. Once 7.0 is on staging, generate one invoice, one packing slip, and one receipt, and actually open them. Look at the layout, the fonts, and any non-Latin text. If invoices auto-attach to order emails, push a test order through and confirm the attachment arrives and opens.

If anything looks off and your plugin renders on the server, that is your cue. The fix is not another font pack. It is moving the rendering off the box before the next core release makes the same point louder.

Paperbolt is free on WordPress.org, 100 PDFs a month, already tested up to 7.0. Prefer to skip the plugin and call the API yourself? The docs have every endpoint.

[Boost]

Digital Troubadour — Sat, 18 Apr 2026 20:36:56 +0000

GovDev

Apr 18

Scraping SAM.gov + USASpending for Federal Contracts (No API Key, in Python)

#python #webscraping #automation #tutorial

5 min read

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.