How to test webhooks locally for Stripe

1# macOS
2brew install stripe/stripe-cli/stripe
3
4# Windows (scoop)
5scoop bucket add stripe https://github.com/stripe/scoop-stripe-cli.git
6scoop install stripe
7
8# Linux (Debian/Ubuntu)
9curl -s https://packages.stripe.dev/api/security/keypair/stripe-cli-gpg/public | gpg --dearmor | sudo tee /usr/share/keyrings/stripe.gpg
10echo "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
11sudo apt update && sudo apt install stripe
12
13# Verify installation
14stripe version

1# Log in to Stripe (opens browser for OAuth)
2stripe login
3
4# Or use an API key directly (useful for CI)
5stripe login --api-key sk_test_yourTestKey

1# Forward all events to your local server
2stripe listen --forward-to localhost:3000/webhook
3
4# Output:
5# Ready! Your webhook signing secret is whsec_abc123...
6# (use this secret for signature verification in your local server)
7
8# Forward only specific events:
9stripe listen --forward-to localhost:3000/webhook \
10  --events payment_intent.succeeded,payment_intent.payment_failed,customer.subscription.created

1// .env (for local development)
2STRIPE_WEBHOOK_SECRET=whsec_abc123...  // From 'stripe listen' output
3
4// Your webhook handler stays the same:
5const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
6
7app.post('/webhook',
8  express.raw({ type: 'application/json' }),
9  (req, res) => {
10    const sig = req.headers['stripe-signature'];
11    let event;
12    try {
13      event = stripe.webhooks.constructEvent(
14        req.body,
15        sig,
16        process.env.STRIPE_WEBHOOK_SECRET // Uses CLI secret locally
17      );
18    } catch (err) {
19      return res.status(400).send(`Webhook Error: ${err.message}`);
20    }
21    console.log('Event received:', event.type);
22    res.json({ received: true });
23  }
24);

1# Trigger a payment_intent.succeeded event
2stripe trigger payment_intent.succeeded
3
4# Trigger a subscription lifecycle
5stripe trigger customer.subscription.created
6
7# Trigger a dispute
8stripe trigger charge.dispute.created
9
10# Trigger an invoice payment failure
11stripe trigger invoice.payment_failed
12
13# Trigger a checkout session completion
14stripe trigger checkout.session.completed
15
16# List all available trigger events
17stripe trigger --list

1# The CLI shows delivery status for each event:
2#   --> payment_intent.succeeded [evt_1ABC] -> localhost:3000/webhook [200]
3#   --> payment_intent.payment_failed [evt_2DEF] -> localhost:3000/webhook [400]
4
5# Replay a specific event
6stripe events resend evt_1ABCxyz
7
8# View recent events in your account
9stripe events list --limit 10
10
11# Get details of a specific event
12stripe events retrieve evt_1ABCxyz
13
14# Common issues and fixes:
15# 400 error → Signature verification failing → Check STRIPE_WEBHOOK_SECRET matches CLI output
16# Connection refused → Server not running → Start your server on port 3000
17# Timeout → Handler too slow → Return 200 immediately, process async