Webhook Guides

Receive Stripe Webhooks Locally

Local Stripe webhook testing should exercise the same request path you expect in production: realistic Stripe events, raw-body signature verification, destination responses, retries, and duplicate-safe handling.

FastHook lets you register a stable source URL, route Stripe events to a CLI destination, and forward those deliveries to localhost. You can inspect the inbound Stripe request and the local receiver response in one place before moving the same flow to staging or production.

Local architecture

StageToolResponsibility
Stripe eventStripe Dashboard or Stripe CLICreate realistic billing events.
IngressFastHook sourceCapture request and preserve headers/body.
ForwardingFastHook CLI destinationDeliver accepted events to localhost.
ReceiverYour local appVerify signature and process idempotently.

Start local forwarding

Create a CLI destination, connect it to the Stripe source, then run the CLI tunnel against your local port. Use a dedicated local source and destination so replay does not mix with production billing traffic.

Forward to localhost
fasthook tunnel --destination des_local_stripe --to 3000

Generate Stripe test events

Stripe CLI can generate representative test events. If your receiver verifies Stripe-Signature, make sure the raw body arrives unchanged at the local receiver.

Stripe CLI test
stripe listen --forward-to https://hook-xxxxxx.fasthook.io/
stripe trigger checkout.session.completed
stripe trigger invoice.paid

Local debugging checklist

  1. Confirm FastHook captured the Stripe request and stored Stripe-Signature.
  2. Confirm the connection filter matched the event type.
  3. Confirm the CLI destination is connected to the right local port and path.
  4. Read the local receiver response body from the FastHook attempt.
  5. Fix local code, retry one failed event, and test duplicate delivery before replay.

Signature boundary

For Stripe, the safest pattern is to verify Stripe-Signature in your billing receiver using Stripe's library and the exact raw request body. If you transform the event before delivery, verify FastHook's destination signature for the transformed request instead.

Keep environments separate

Do not reuse one source for local, staging, and production Stripe endpoints. Stripe signing secrets, event destinations, and replay expectations differ across environments, and mixing them makes billing incidents harder to reason about.

A clean local setup has its own Stripe test-mode endpoint, FastHook source, CLI destination, and receiver configuration. When the test passes, move the same route design into staging rather than pointing live Stripe traffic at a development tunnel.

  • Use Stripe test mode for local webhook events.
  • Use a dedicated FastHook CLI destination per developer or service.
  • Keep local replay windows small and clearly labeled.
  • Never test destructive billing side effects with production customer objects.

Related guides