STRIPE EDITION

Webhooks
for Dummies

For Dummies Character

Stop fighting with ngrok and localhost tunnels.
Test Stripe payments locally in 5 minutes.

YOUR ENDPOINT:
macOS (Homebrew)
brew install stripe/stripe-cli/stripe
Windows (Scoop)
scoop bucket add stripe https://github.com/stripe/scoop-stripe-cli.git
scoop install stripe
Linux (apt)
curl -s https://packages.stripe.dev/api/security/keypair/stripe-cli-gpg/public | gpg --dearmor | sudo tee /usr/share/keyrings/stripe.gpg
echo "deb [signed-by=/usr/share/keyrings/stripe.gpg] https://packages.stripe.dev/stripe-cli-debian-local stable main" | sudo tee -a /etc/apt/sources.list.d/stripe.list
sudo apt update
sudo apt install stripe
Direct Download
# Visit: https://github.com/stripe/stripe-cli/releases

SOMETHING BROKEN?

Here are the most common webhook issues and how to fix them.

"No signatures found matching the expected signature"

POSSIBLE CAUSES:
  • •Wrong webhook secret (whsec_...)
  • •Body was parsed as JSON before verification
  • •Using production secret in test mode
THE FIX:

Make sure bodyParser is disabled and you're using the secret from 'stripe listen' output

"Webhook endpoint not receiving events"

POSSIBLE CAUSES:
  • •Wrong port number
  • •Wrong endpoint path
  • •Firewall blocking connection
THE FIX:

Verify your endpoint URL matches exactly. Check 'stripe listen' output for the forwarding URL.

"400 Bad Request from webhook"

POSSIBLE CAUSES:
  • •Signature verification failing
  • •Missing stripe-signature header
  • •Malformed request body
THE FIX:

Log the error message from constructEvent(). It tells you exactly what's wrong.

"Webhook times out"

POSSIBLE CAUSES:
  • •Endpoint taking too long (>30s)
  • •Doing too much work synchronously
THE FIX:

Return 200 immediately, then process async. Use a queue for heavy work.

PRO TIPS

  • →Keep stripe listen running in a dedicated terminal tab while developing.
  • →Use --print-json to see the full webhook payload for debugging.
  • →Test idempotency: Stripe may retry webhooks. Handle duplicates.
  • →Return 200 fast: Do heavy work async to avoid timeouts.
  • →Production tip: Use the Dashboard webhook secret, not the CLI one.

⚡ QUICK REFERENCE

START LISTENING
TEST PAYMENT
SEE ALL EVENTS
Little Exits
Stripe Docs →CLI GitHub →