HookNexus
Stripe Replay

How to Replay Stripe Webhook Events During Local Development

Replay saved Stripe webhook requests during local development so you can validate handler changes without recreating the original event.

Start Debugging Free Read the Docs

To replay a Stripe webhook event locally, capture the original request with a webhook debugger and then resend the saved payload to your localhost handler using a replay tool. This lets you validate handler changes against real Stripe payloads without going through the Stripe Dashboard to recreate the event. Replaying is especially valuable for checkout.session.completed, invoice.payment_succeeded, and subscription lifecycle events — payloads that require multiple user or API actions to produce. Once the request is captured, you can replay it dozens of times while iterating on your code, cutting minutes off every test cycle.

Why replay is faster than re-triggering Stripe events

Recreating a Stripe webhook event the “normal” way means performing the action that originally generated it. For a checkout.session.completed event, that means opening a Checkout page, entering test card details, and completing the purchase. For a customer.subscription.updated event, it means changing a subscription through the Dashboard or API and waiting for Stripe to fire the hook. Each round trip can take 30 seconds to several minutes depending on the flow.

Replay eliminates all of that. If you already have the original payload stored — either in your HookNexus request log or exported as JSON — you can resend it to your local handler in under a second. The payload is identical to what Stripe originally delivered, so your handler processes the same headers, body, and event structure.

The iteration loop with replay

  1. You receive a Stripe webhook that exposes a bug.
  2. You fix the handler code.
  3. You replay the saved event instead of repurchasing or re-subscribing.
  4. You confirm the fix, push, and move on.

Without replay, step 3 alone could take longer than all the other steps combined. For teams that handle complex billing flows with coupons, trials, or metered usage, the time savings multiply across every developer on the project.

When replay makes sense (and when it doesn’t)

Replay is powerful but not a universal replacement for live Stripe event delivery. Understanding the boundaries will help you choose the right approach for each situation.

Best scenarios for replay

  • You fixed a bug and need another pass. The most common use case. You already have the payload that triggered the failure, so replaying it validates the fix directly.
  • Comparing multiple code versions. When refactoring a webhook handler, replay the same event against each version to confirm parity. This is especially useful when migrating from a monolithic handler to individual event processors.
  • The original Stripe action is expensive or tedious. Events tied to multi-step checkout flows, subscription upgrades, or dispute workflows are slow to reproduce manually. Replay lets you skip the setup.
  • Onboarding a new teammate. Share a set of representative payloads so a new developer can replay them locally and understand how each event flows through the handler without needing Stripe test mode credentials.

When NOT to use replay

  • You need a fresh event with new data. If you changed your Stripe product catalog or price IDs, old payloads contain outdated references. You need a new live event.
  • Testing event ordering or timing. Replay delivers a single event on demand. It cannot simulate the timing gaps between invoice.created, invoice.paid, and charge.succeeded that Stripe delivers asynchronously.
  • The webhook secret has rotated. If you regenerated your Stripe endpoint secret after capturing the event, signature verification will fail on the replayed request unless you skip verification in development or re-sign the payload.
  • You need to test Stripe retry behavior. Stripe retries follow an exponential backoff schedule. Replay delivers once, immediately.

How to replay a Stripe webhook event step by step

This walkthrough uses HookNexus to capture and replay events. The same principles apply if you export the payload manually and use curl.

Step 1 — Capture the original event first

Before you can replay anything, you need a stored copy of the webhook delivery. Point your Stripe webhook endpoint at your HookNexus URL so every incoming event is logged automatically.

In your Stripe Dashboard under Developers > Webhooks, set the endpoint URL to your HookNexus endpoint:

https://api.hooknexus.com/h/your-endpoint-id

Then trigger the Stripe event you need — complete a test checkout, update a subscription, or create a refund. HookNexus captures the full request including headers, body, and metadata. You can also use the Stripe CLI to forward events during initial development.

Step 2 — Fix your handler code

Open your webhook handler and make the necessary changes. For example, suppose your invoice.payment_succeeded handler was not correctly updating the subscription period:

app.post("/webhooks/stripe", async (req, res) => {
  const event = req.body;

  if (event.type === "invoice.payment_succeeded") {
    const invoice = event.data.object;
    const subscriptionId = invoice.subscription;

    await db.subscriptions.update({
      where: { stripeSubscriptionId: subscriptionId },
      data: {
        currentPeriodEnd: new Date(invoice.lines.data[0].period.end * 1000),
        status: "active",
      },
    });

    console.log(`Subscription ${subscriptionId} period updated`);
  }

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

Save the file but do not redeploy yet — you want to validate the fix locally first.

Step 3 — Replay from the dashboard or CLI

Open the HookNexus dashboard, find the captured invoice.payment_succeeded event in your request log, and click Replay. The original payload is sent to your local handler at the forwarding address you configured. See the replay guide for detailed dashboard instructions.

If you prefer the command line:

hooknexus listen your-endpoint-id --forward http://localhost:3000/webhooks/stripe

Then trigger the replay from the dashboard or API. Your local server receives the exact same payload Stripe originally sent.

Step 4 — Compare the response

After your handler processes the replayed event, check the response code and body in the HookNexus dashboard. A 200 status confirms your handler accepted the payload. Cross-reference with your local database or logs to verify the subscription period was updated correctly.

If the response indicates an error, fix the code and replay again — no need to return to Stripe. Repeat until the handler behaves as expected. When you encounter signature verification failures, check whether the signing secret matches the one used when the event was originally captured.

Writing idempotent handlers for safe replay

Replaying events means your handler might process the same event ID more than once. In production, Stripe itself retries failed deliveries, so idempotency is not just a replay concern — it is a requirement for correctness. An idempotent handler produces the same outcome regardless of how many times it receives the same event.

Checking for duplicate event IDs

The simplest approach is to track processed event IDs and skip duplicates:

app.post("/webhooks/stripe", async (req, res) => {
  const event = req.body;

  const existing = await db.processedEvents.findUnique({
    where: { eventId: event.id },
  });

  if (existing) {
    console.log(`Event ${event.id} already processed, skipping`);
    return res.status(200).json({ received: true });
  }

  // Process the event
  await handleStripeEvent(event);

  await db.processedEvents.create({
    data: {
      eventId: event.id,
      eventType: event.type,
      processedAt: new Date(),
    },
  });

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

This pattern stores each event ID after successful processing. On replay or retry, the handler finds the existing record and returns 200 without running the business logic again.

Why idempotency matters for both replay and production retries

Stripe retries webhook delivery up to several times over approximately 72 hours when your endpoint returns a non-2xx response. Without idempotency, a handler that creates a database record on each invocation would produce duplicates during retries. Replay amplifies this risk because you might replay the same event many times while iterating on code.

Design your handler so that repeated processing of the same event.id never creates duplicate charges, sends duplicate emails, or provisions duplicate resources. Use database unique constraints on the event ID column as a safety net in addition to the application-level check.

For a broader look at testing your Stripe integration end to end, see the Stripe webhook testing guide.

Replay checklist

Before replaying a Stripe webhook event locally, run through this list:

  • The original event is captured and stored in your request log
  • Your local server is running and reachable at the forwarding address
  • Your handler includes idempotency logic to handle repeated event IDs safely
  • The webhook signing secret matches the one used when the event was captured
  • Downstream side effects (emails, charges, provisioning) are disabled or sandboxed in development
  • You have verified the event payload structure has not changed since capture
  • Your database is in a clean or predictable state for the test

Frequently asked questions

Can I replay a Stripe webhook event that was originally sent to production?

Yes. If you captured the production delivery — for example, by logging the full request body — you can replay that payload against your local development handler. Be careful with production payloads that contain real customer data. Ensure your local environment does not send real emails, create real charges, or leak sensitive data. Use environment flags to disable side effects during local testing.

Does replaying change the Stripe event ID or timestamp?

No. A replay sends the exact same payload that Stripe originally delivered, including the original event.id, created timestamp, and all nested objects. Your handler sees an identical request. This is why idempotency checks are essential — the event ID will be the same on every replay.

How is replay different from using stripe trigger in the Stripe CLI?

The stripe trigger command generates a synthetic event with sample data. It is useful for initial development when you do not have real events yet. Replay, on the other hand, resends a real event that actually occurred in your Stripe account. The payload contains real product IDs, customer IDs, and amounts. Replay is better for debugging production issues because the data matches exactly what caused the problem. See the Stripe webhook testing overview for a comparison of testing approaches.

What happens if my handler returns an error during replay?

The replay tool records the error response so you can inspect it. Unlike Stripe’s own retry mechanism, replay does not automatically retry on failure — you decide when to replay again after fixing the issue. This gives you full control over the debugging loop.

Next steps