DEV Community: WebhookProof

Stripe webhook timestamp outside the tolerance zone? Fix the clock, don't set tolerance to 0

WebhookProof — Fri, 13 Nov 2026 15:03:34 +0000

A webhook handler can pass every signature check and still reject the event because it looks too old. The fix people reach for first is setting the tolerance to 0, which makes the error disappear. Stripe's docs name that as a mistake.

This post covers what the timestamp in the Stripe-Signature header is for, what Stripe says about the default tolerance, what it recommends for server clocks, and why retries aren't the cause. Every claim links to the doc it comes from (see Sources at the end).

What the timestamp is for

Stripe's docs describe the threat: "A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them." To mitigate it, "Stripe includes a timestamp in the Stripe-Signature header."

That timestamp can't be edited on the way: "Because this timestamp is part of the signed payload, it's also verified by the signature, so an attacker can't change the timestamp without invalidating the signature."

So the signature proves the payload is Stripe's, and the timestamp lets the application decide whether it arrived recently enough. Per the docs: "If the signature is valid but the timestamp is too old, you can have your application reject the payload."

The default tolerance

Stripe states: "Our libraries have a default tolerance of 5 minutes between the timestamp and the current time." The docs add: "You can change this tolerance by providing an additional parameter when verifying signatures."

An error about the timestamp being outside the tolerance therefore means the gap between the signed timestamp and the current time, as the verifying code sees it, was larger than the allowed window. Two places can produce that gap: the signed timestamp is old, or the server's idea of "now" is off.

Fix the clock

Stripe's instruction: "Use Network Time Protocol (NTP) to make sure that your server's clock is accurate and synchronizes with the time on Stripe's servers."

Practical checks:

Confirm the host or VM that runs the webhook handler has time synchronization turned on.
Log the difference between the current time and the t= value of each incoming Stripe-Signature header. A consistent offset points to clock drift.
Check where verification happens. If the raw body and header are stored and verified later, the age is measured at that later moment. Verify in the request handler, then hand work to a queue. Stripe asks the endpoint to "quickly return a successful status code (2xx) before any complex logic that could cause a timeout."

// Verify on receipt, using the default tolerance. Don't pass 0.
const event = stripe.webhooks.constructEvent(
  rawBody,
  req.headers['stripe-signature'],
  process.env.STRIPE_WEBHOOK_SECRET
);
// ...return 2xx now, do the slow work in a worker

Retries are not the cause

After downtime it's tempting to blame old retried events. Stripe's docs say otherwise: "Stripe generates the timestamp and signature each time we send an event to your endpoint. If Stripe retries an event (for example, your endpoint previously replied with a non-2xx status code), then we generate a new signature and timestamp for the new delivery attempt."

A retried delivery carries a fresh timestamp. If retries fail with a timestamp error, the clock or a delayed verification step is the place to look.

Why a tolerance of 0 is a trap

Stripe lists it as a common mistake: "Don't use a tolerance value of 0. Using a tolerance value of 0 disables the recency check entirely."

With the recency check off, a captured payload and signature can be re-sent later and still pass. That's the replay attack the timestamp exists to stop. A very large tolerance gives much of the same exposure, so the clock is the thing to correct.

A related habit: replaying a saved payload by hand. A body and signature header copied from a log will fail once they're past the tolerance window. That's the protection working, not a bug. For testing, trigger a fresh event so Stripe signs a new timestamp.

Checklist

[ ] Signature verification runs in the request handler, on the raw body
[ ] The default tolerance is used (no 0, no huge value)
[ ] The server clock is synchronized with NTP
[ ] The offset between current time and t= is logged while debugging
[ ] The handler returns a 2xx before slow work
[ ] Hand-replayed payloads are expected to fail once they're older than the window

A rejected timestamp is one of several ways a webhook endpoint can misbehave without anyone noticing. WebhookProof's free checker sends 3 harmless test requests to a webhook URL you own and reports whether Stripe can reach it and whether unsigned requests are rejected. The full guide is here: Stripe webhook timestamp outside the tolerance zone

WebhookProof is an independent tool, not affiliated with Stripe, Inc. Quotes are from the linked documentation as read on 2026-11-13.

Sources

Stripe, Receive Stripe events in your webhook endpoint (Preventing replay attacks, default tolerance, NTP, tolerance 0, retries and new timestamps, quickly return a 2xx response): https://docs.stripe.com/webhooks

Stripe webhook timed out? Return a 2xx first, then do the heavy work in a queue

WebhookProof — Wed, 11 Nov 2026 15:02:33 +0000

A webhook handler often does everything inside the request: verify the event, update the database, send the email, call another API, and only then answer. On a quiet day that finishes in time. On a busy one, or when a downstream service is slow, the response arrives late and Stripe's delivery log shows a timeout.

This post covers what that status means, what Stripe says the handler should do first, how to move the slow part into a queue, and how to catch up on events that failed in the meantime. Every claim links to the doc it comes from (see Sources at the end).

How to tell if the endpoint is timing out

Open the webhook endpoint in the Stripe Dashboard and go to the Event deliveries tab. Stripe's docs describe it as a list of events and whether they're Delivered, Pending, or Failed, and clicking an event shows "the HTTP status code of the delivery attempt and the time of pending future deliveries."
Look for the (Timed out) ERR status. Stripe's description: "The destination server took too long to respond to the webhook request."
Compare the timed-out events with what the handler does before it responds. Anything slow that runs ahead of the response is a suspect.

What Stripe asks the handler to do

Stripe's fix for the timed-out status is: "Make sure you defer complex logic and return a successful response immediately in your webhook handling code."

The handler guidance says the same thing in more detail. The endpoint should be set up so that it:

"Verifies the webhook request is generated by Stripe using the JSON payload, the Stripe-Signature header, and the whsec_ webhook signing secret."
"Quickly returns a successful status code (2xx) before any complex logic that might cause a timeout."

Stripe gives an example: "you must return a 200 response before updating a customer's invoice as paid in your accounting system."

So the order is: verify the signature, return 2xx, then do the work.

Why a slow response is worse than it looks

A timeout isn't a quiet event. Stripe counts it as a failed delivery and retries: "Stripe attempts to deliver events to your destination for up to three days with an exponential back off in live mode." Sandbox events are retried "three times over the course of a few hours."

Each retry is a second chance for the same work to run, so the handler can also see duplicates. Stripe notes that "Webhook endpoints might occasionally receive the same event more than once" and recommends "logging the event IDs you've processed, and then not processing already-logged events."

Hand the work to a queue

Stripe recommends asynchronous processing directly: "Configure your handler to process incoming events with an asynchronous queue." Its reasoning: "You might encounter scalability issues if you choose to process events synchronously. Any large spike in webhook deliveries (for example, during the beginning of the month when all subscriptions renew) might overwhelm your endpoint hosts." And: "Asynchronous queues allow you to process the concurrent events at a rate your system can support."

The handler's only jobs are to verify, store or enqueue, and answer.

// Verified webhook handler: verify, enqueue, answer. Nothing slow before the response.
export async function POST(req) {
  const body = await req.text(); // raw body, unmodified, for signature verification
  let event;
  try {
    event = stripe.webhooks.constructEvent(
      body,
      req.headers.get('stripe-signature'),
      process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch (err) {
    return new Response('bad signature', { status: 400 });
  }

  // Record the event ID; skip it if it's already been seen.
  const isNew = await queue.enqueueOnce(event.id, event);

  // The slow work (database writes, emails, third-party calls) runs in a worker.
  return new Response('ok', { status: 200 });
}

// Worker, outside the request. Safe to run twice for the same event ID.
async function processEvent(event) {
  if (await alreadyProcessed(event.id)) return;
  await markProcessing(event.id);
  // grant access, send the email, update the accounting system...
  await markProcessed(event.id);
}

Two details from Stripe's docs matter here. First, the raw body: "Stripe requires the raw body of the request to perform signature verification. If you're using a framework, make sure it doesn't manipulate the raw body." Second, Stripe doesn't promise order: "Stripe doesn't guarantee the delivery of events in the order that they're generated," so the worker shouldn't depend on one event arriving before another.

Fix the failures that already happened

Stripe retries on its own, but a slow backlog can be cleared faster. For events that failed during an outage or slowdown, Stripe's docs say to call the List Events API with:

ending_before: "An event ID that was successfully delivered immediately before the outage."
types: "The event types your endpoint listens for."
delivery_success: "Set to false to return only events that failed delivery to at least one of your endpoints."

"Stripe only returns events created in the last 30 days." The response "returns up to 10 events" by default, and ending_before with auto-pagination "returns events in chronological order."

Manual processing has one catch: "Stripe still considers manually processed events as undelivered and continues its automatic retry schedule. When your endpoint receives an event you've already processed, skip it and return a 200 response to stop further retries." That's why the worker above checks the event ID before doing anything.

For single events, "In the Stripe Dashboard, click Resend when looking at a specific event. This works for up to 15 days after the event creation." The Stripe CLI works "for up to 30 days." Stripe adds that "Manually resending an event that failed to reach a webhook endpoint doesn't cancel Stripe's automatic retry behavior, even if it results in a 2xx status code."

Things that keep the timeout coming back

Work before the response. Any database write, email, or third-party API call ahead of return 200 can stretch the response past the limit.
Verification that isn't the problem. Signature checks belong before the 2xx, as Stripe lists, so keep them. Move everything after them.
No queue under load. A burst, such as renewals at the start of the month, can overwhelm a handler that processes events inline.
Wrong status on skipped events. If a duplicate is skipped but the handler doesn't answer 200, Stripe keeps retrying.

Checklist

[ ] Event deliveries shows no (Timed out) entries, or each one has been traced to slow work before the response
[ ] The handler verifies the signature on the raw body, then returns a 2xx
[ ] Nothing slow (database, email, third-party APIs) runs before the response
[ ] Events go to an asynchronous queue and a worker processes them
[ ] The worker logs event IDs and skips events it has already processed
[ ] The handler doesn't depend on events arriving in a particular order
[ ] Failed events from the last 30 days have been listed with delivery_success=false and processed

A timeout is one of several ways an endpoint can fail without anyone noticing. WebhookProof's free checker sends 3 harmless test requests to a webhook URL you own and reports whether Stripe can reach it and whether unsigned requests are rejected. The full guide is here: Stripe webhook timed out?

WebhookProof is an independent tool, not affiliated with Stripe, Inc. Quotes are from the linked documentation as read on 2026-11-09.

Sources

Stripe, Receive Stripe events in your webhook endpoint (handler steps, (Timed out) status and fix, event deliveries, automatic and manual retries, event ordering, duplicate events, handle events asynchronously, quickly return a 2xx response): https://docs.stripe.com/webhooks
Stripe, Manage webhook endpoints (process undelivered events, List Events parameters, 30-day window, respond to automatic retries, async queue, quickly return a 2xx response): https://docs.stripe.com/events/manage-webhook-endpoints

Refunded or disputed, but the customer still has access? Your Stripe webhook only listens for the purchase

WebhookProof — Fri, 06 Nov 2026 15:13:47 +0000

A lot of paywalls handle exactly one Stripe event. checkout.session.completed arrives, the handler sets paid = true, and that's the end of it. Nothing in the code ever sets it back.

So a refund goes out, or a customer's bank opens a dispute, or a subscription ends, and the database still says paid. The app keeps the door open for someone who's no longer paying. This post covers the events that should take access away, how to tie them back to the right user, and the edge cases worth deciding on up front. Every claim links to the doc it comes from (see Sources at the end).

How to tell if access is one-way

Open the webhook endpoint in the Stripe Dashboard and look at the events it's subscribed to. If the list is only checkout or payment-success events, Stripe never tells the app about refunds or disputes.
Refund a test-mode purchase, then reload the app as that test user. If the paid content is still there, access only ever goes one direction.
Search the handler for charge.refunded, charge.dispute.created and customer.subscription.deleted. If none of them appear, nothing revokes access.

The events that should take access away

From Stripe's list of event types:

charge.refunded: "Occurs whenever a charge is refunded, including partial refunds."
charge.dispute.created: "Occurs whenever a customer disputes a charge with their bank."
charge.dispute.closed: "Occurs when a dispute is closed and the dispute status changes to lost, warning_closed, or won." This is the one to use for giving access back after a dispute is won.
refund.failed: "Occurs whenever a refund has failed." Stripe's refund docs say that in that case "you need to arrange an alternative way to provide your customer with a refund."

For subscriptions, Stripe's cancellation docs describe customer.subscription.deleted as "Sent when a subscription is canceled. The cancellation can result from a direct call to delete the subscription or when a subscription with cancel_at_period_end: true reaches the end of its billing period."

Setting cancel_at_period_end doesn't end anything yet. The same docs say customer.subscription.updated is "Sent for any subscription update, including when cancel_at_period_end is set to true." The customer has paid through the end of the period, so keep access until the deleted event arrives.

Each of these has to be added to the endpoint's event list, in the Dashboard or through enabled_events on the endpoint. Stripe only sends the events an endpoint is subscribed to. Stripe's refund docs also recommend that you "verify webhook signatures" for these events, which matters because the same handler that revokes access also grants it.

Map the event back to the user

Refund and dispute events carry a Charge or a Dispute, not the Checkout Session that granted access. Both point back to the payment:

On the Charge object, payment_intent is the "ID of the PaymentIntent associated with this charge."
On the Dispute object, payment_intent is the "ID of the PaymentIntent that’s disputed," and charge is the "ID of the charge that’s disputed."

The Checkout Session object has a payment_intent field too. So at fulfillment time, store the session's payment_intent next to the user. Revoking then becomes a single lookup.

// Inside a verified webhook handler (signature already checked on the raw body)
switch (event.type) {
  case 'checkout.session.completed': {
    const s = event.data.object;
    await grantAccess(s.client_reference_id, { paymentIntent: s.payment_intent });
    break;
  }
  case 'charge.refunded': {
    const charge = event.data.object;
    // refunded is true only for a full refund; decide what a partial refund means
    if (charge.refunded) await revokeByPaymentIntent(charge.payment_intent, 'refunded');
    break;
  }
  case 'charge.dispute.created':
    await revokeByPaymentIntent(event.data.object.payment_intent, 'disputed');
    break;
  case 'charge.dispute.closed':
    if (event.data.object.status === 'won') {
      await restoreByPaymentIntent(event.data.object.payment_intent);
    }
    break;
  case 'customer.subscription.deleted':
    await revokeBySubscription(event.data.object.id, 'canceled');
    break;
}
return new Response('ok', { status: 200 });

Decide the edge cases before they happen

Partial refunds. charge.refunded fires for those too. On the Charge, refunded means "Whether the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false," and amount_refunded holds the refunded amount. Pick a rule, such as revoking only on a full refund, and write it down.

Inquiries. Stripe's dispute docs explain that "Some card networks initiate a preliminary phase before creating a formal dispute," which Stripe calls an inquiry, and that in the API an inquiry's status "is prepended with warning," as in warning_needs_response. The same page notes the bank often asks "because the cardholder doesn’t recognize the transaction description." To avoid cutting off a customer over a confusing statement line, revoke on formal dispute statuses and leave warning_ statuses alone.

Disputes that are won. When charge.dispute.closed arrives with status won, restore access, as in the switch above.

Things that make revocation fail quietly

Access granted by the success page. If /success unlocks access on its own, a webhook can't keep it revoked. Grant from the webhook and have the page only read the database.
Duplicate deliveries. The same event can arrive more than once, so revoke and restore should be safe to run twice.
An endpoint Stripe can't reach. Then neither grants nor revokes arrive at all.

Clean up the customers who already kept access

Stripe's refund docs point to a Dashboard view of refunded payments. To catch disputes as well, page through charges with the API and check refunded and disputed ("Whether the charge has been disputed") on each one. Revoke each match with the same function the webhook now calls.

Checklist

[ ] The endpoint subscribes to charge.refunded, charge.dispute.created, charge.dispute.closed and customer.subscription.deleted
[ ] Fulfillment stores the Checkout Session's payment_intent with the user
[ ] Revoke runs only for a full refund, or a written rule covers partial ones
[ ] warning_ inquiry statuses are handled on purpose
[ ] cancel_at_period_end keeps access until customer.subscription.deleted
[ ] A won dispute restores access
[ ] Past refunds and disputes have been cleaned up

None of this helps if Stripe can't reach the endpoint in the first place. WebhookProof's free checker sends 3 harmless test requests to a webhook URL you own and reports whether Stripe can reach it and whether unsigned requests are rejected. The full guide, with the revoke logic and a cleanup approach, is here: Refunded or disputed Stripe payment still has access?

WebhookProof is an independent tool, not affiliated with Stripe, Inc. Quotes are from the linked documentation as read on 2026-11-04.

Sources

Stripe API, Types of events (charge.refunded, charge.dispute.created, charge.dispute.closed, refund.failed): https://docs.stripe.com/api/events/types
Stripe, Refund and cancel payments (alternative refund when refund.failed, verify webhook signatures, Dashboard view of refunded payments): https://docs.stripe.com/refunds
Stripe, Cancel subscriptions (customer.subscription.deleted, customer.subscription.updated when cancel_at_period_end is set): https://docs.stripe.com/billing/subscriptions/cancel
Stripe API, The Charge object (payment_intent, refunded, amount_refunded, disputed): https://docs.stripe.com/api/charges/object
Stripe API, The Dispute object (payment_intent, charge): https://docs.stripe.com/api/disputes/object
Stripe API, The Checkout Session object (payment_intent): https://docs.stripe.com/api/checkout/sessions/object
Stripe, How disputes work (inquiries, warning_ statuses): https://docs.stripe.com/disputes/how-disputes-work

Customers paid while your Stripe webhook was down? How to find and recover every missed order

WebhookProof — Mon, 02 Nov 2026 15:04:14 +0000

A webhook endpoint breaks: a bad deploy, an expired secret, a new redirect, a login wall in front of the route. Checkout keeps working, so customers keep paying. Your app just never hears about it.

Once the endpoint is fixed, the next question is the one that matters for revenue: who paid in the meantime, and how do they get what they bought? This post walks through Stripe's documented recovery path, step by step. Every claim links to the doc it comes from (see Sources at the end).

First, how much time Stripe gives you

Stripe doesn't drop a failed event right away. From the webhook docs: "Stripe attempts to deliver events to your destination for up to three days with an exponential back off in live mode." In a sandbox it's shorter: "We retry event deliveries created in a sandbox three times over the course of a few hours."

There's one way to lose those retries. Stripe: "If your destination has been disabled or deleted when we attempt a retry, we prevent future retries of that event." And from the event destinations docs: "Stripe won't attempt to resend any events generated while the destination is disabled."

So when an endpoint is failing, fix the URL or the code behind it. Don't delete or disable the endpoint to make the errors stop.

Step 1: Confirm the live endpoint is enabled

List your webhook endpoints with your live secret key. Each endpoint has a status, and Stripe's API reference says it "can be enabled or disabled."

curl -G https://api.stripe.com/v1/webhook_endpoints -u "$STRIPE_LIVE_KEY:"
# Check each endpoint's "url", "status" and "enabled_events"

Check that the URL is your production URL, the status is enabled, and the event types you fulfill on are in enabled_events.

Step 2: List exactly what failed

Stripe's guide to processing undelivered events says to call the List Events API with three parameters:

ending_before: "An event ID that was successfully delivered immediately before the outage. This anchors the list to the window of events you missed."
types: "The event types your endpoint listens for."
delivery_success: "Set to false to return only events that failed delivery to at least one of your endpoints."

curl -G https://api.stripe.com/v1/events \
  -u "$STRIPE_LIVE_KEY:" \
  -d ending_before=evt_LAST_GOOD_EVENT \
  -d "types[]=checkout.session.completed" \
  -d delivery_success=false

Two limits to know. "Stripe only returns events created in the last 30 days." And "By default, the response returns up to 10 events. To retrieve all events, use auto-pagination."

Step 3: Replay them without doing anything twice

This is where recovery scripts cause new problems. Stripe warns: "Guard against processing the same event twice. Your manual recovery script might run more than once, and Stripe's automatic retries might deliver some events while your script is running."

Stripe's pattern is to check whether an event is already handled, mark it as processing, do the work, then mark it as processed. Here is that shape in Node, using the library's for await auto-pagination:

// recover-missed-events.mjs (Node 18+, stripe npm package)
import Stripe from 'stripe'

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY)

const events = stripe.events.list({
  ending_before: 'evt_LAST_GOOD_EVENT',
  types: ['checkout.session.completed'],
  delivery_success: false,
})

for await (const event of events) {
  // Your own data store: skip anything already being handled or done
  if (await isProcessingOrProcessed(event.id)) continue
  await markAsProcessing(event.id)
  await fulfillCheckout(event.data.object.id)
  await markAsProcessed(event.id)
}

Per Stripe's docs, "Using ending_before with auto-pagination returns events in chronological order, so you process them in the order they were created."

Inside fulfillCheckout, follow Stripe's fulfillment guide: "Retrieve the Checkout Session from the API with the line_items property expanded" and "Check the payment_status property to determine if it requires fulfillment." That way the replay trusts Stripe's current answer, not an old payload.

Step 4: Make the endpoint answer the retries

Processing the backlog yourself doesn't tell Stripe to stop. From the same guide: "Stripe still considers manually processed events as undelivered and continues its automatic retry schedule. When your endpoint receives an event you've already processed, skip it and return a 200 response to stop further retries."

So the webhook handler needs the same "already processed?" check as the script. If it sees an event ID it already handled, it returns 200 and does nothing else.

Only a few events? Resend them instead

For a short outage, Stripe's two manual retry options may be enough:

"In the Stripe Dashboard, click Resend when looking at a specific event. This works for up to 15 days after the event creation."
"With the Stripe CLI, run the stripe events resend <event_id> --webhook-endpoint=<endpoint_id> command. This works for up to 30 days after the event creation."

The same caveat applies: "Manually resending an event that failed to reach a webhook endpoint doesn't cancel Stripe's automatic retry behavior, even if it results in a 2xx status code." Your handler still has to be safe to run twice.

Older than 30 days?

Those events won't come back from the Events API. Rebuild from the payments themselves: the List Checkout Sessions API takes a created filter ("Only return Checkout Sessions that were created during the given date interval") and a status filter, where complete means "The checkout session is complete." Run each session through the same fulfillCheckout function, which checks payment_status and skips anything already granted.

Next time, find out the same day

Stripe's health alerts won't catch this on most accounts. The basic tier, which "All Stripe users receive," covers 402 and 500 error alerts. Webhook latency alerts are in the advanced tier, which is for "Users on Stripe's Growth, Premium or Enterprise Support plan." A small daily job that runs the delivery_success=false query from Step 2 over the last 24 hours works on any account.

Checklist

[ ] The live endpoint is enabled and points at the production URL
[ ] Failing endpoints get fixed, not disabled or deleted, so Stripe keeps retrying
[ ] Missed events are listed with ending_before, types and delivery_success=false, with auto-pagination
[ ] The recovery script and the webhook handler share one "already processed" check
[ ] Already-processed events get a 200 so Stripe stops retrying
[ ] Fulfillment retrieves the Checkout Session and checks payment_status
[ ] Anything older than 30 days is rebuilt from Checkout Sessions
[ ] A daily check flags failed deliveries before customers write in

Before replaying a backlog, it helps to know the endpoint really is fixed. WebhookProof's free checker sends 3 harmless test requests to a webhook URL you own and reports whether Stripe can reach it and whether unsigned requests are rejected. The full guide, including a daily alert script, is here: Is your Stripe webhook failing silently?

WebhookProof is an independent tool, not affiliated with Stripe, Inc. Quotes are from the linked documentation as read on 2026-10-30.

Sources

Stripe, Receive Stripe events in your webhook endpoint (automatic retries for up to three days in live mode, three times in a sandbox, no retries if disabled or deleted, Dashboard resend 15 days, CLI resend 30 days, resend doesn't cancel automatic retries): https://docs.stripe.com/webhooks
Stripe, Manage event destinations (no resend of events generated while a destination is disabled): https://docs.stripe.com/workbench/event-destinations
Stripe API, The Webhook Endpoint object (status can be enabled or disabled): https://docs.stripe.com/api/webhook_endpoints/object
Stripe, Process undelivered webhook events (ending_before, types, delivery_success=false, last 30 days, 10 per page, chronological order, guard against double processing, manually processed events still retried, return 200): https://docs.stripe.com/webhooks/process-undelivered-events
Stripe API, Auto-pagination (for await in Node): https://docs.stripe.com/api/pagination/auto
Stripe, Fulfill orders, full-page Checkout (retrieve the Checkout Session, check payment_status): https://docs.stripe.com/checkout/fulfillment?ui=full-page
Stripe API, List all Checkout Sessions (created and status filters): https://docs.stripe.com/api/checkout/sessions/list
Stripe, Health alerts (basic tier 402/500 for all users, advanced tier for Growth, Premium or Enterprise support plans, webhook latency alerts): https://docs.stripe.com/health-alerts

Can someone fake a Stripe payment to your app? Only if your webhook skips the signature check

WebhookProof — Wed, 28 Oct 2026 14:11:47 +0000

Here's a question worth asking about any app that sells something through Stripe: what happens if someone who never paid sends your webhook endpoint a JSON body that looks like a completed checkout?

If the endpoint checks Stripe's signature, nothing happens. The request is rejected. If it doesn't, your app grants access, sends the download link, or writes the order, exactly as if the payment were real. This post covers why that works, what Stripe recommends against it, and how to test your own endpoint in one command. Every claim links to the doc it comes from (see Sources at the end).

Stripe spells out the risk

From Stripe's webhook docs: "Without verification, an attacker could send fake webhook events to your endpoint to trigger actions like fulfilling orders, granting account access, or modifying records. Always verify that webhook events originate from Stripe before acting on them."

A webhook endpoint is just a public URL that accepts POST requests. Nothing about HTTP proves who sent the request. The JSON body carries no proof either: anyone can type "type": "checkout.session.completed".

Why a hidden URL doesn't help

It's tempting to think an obscure path is enough. In practice, webhook routes follow a few familiar patterns (/api/webhooks/stripe, /api/stripe/webhook), they show up in tutorials and generated code, and they end up in public repos. Treat the URL as public and rely on the checks below instead.

What Stripe says protects you

Stripe's docs list two protections and say to "Use both of these protections":

Signature verification. "Stripe signs every webhook event by including a signature in the Stripe-Signature header. Verify this signature using our official libraries or manually to confirm that the event wasn't sent or modified by a third party."
IP allowlisting. "Stripe sends webhook events from a set list of IP addresses. Configure your server or firewall to only accept webhook requests from these addresses." The current list is on Stripe's IP addresses page.

The signature is computed with a secret only Stripe and your server know. Stripe: "Stripe generates signatures using a hash-based message authentication code (HMAC) with SHA-256." Each endpoint has its own: "Stripe generates a unique secret key for each endpoint. If you use the same endpoint for both test and live API keys, the secret is different for each one."

With the official Node library, verification is one call. It needs the raw request body, the header, and the endpoint's whsec_ secret:

// Next.js App Router route handler
import Stripe from 'stripe'

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)

export async function POST(req: Request) {
  const body = await req.text() // raw body, not parsed JSON
  const sig = req.headers.get('stripe-signature')

  let event: Stripe.Event
  try {
    event = stripe.webhooks.constructEvent(body, sig!, process.env.STRIPE_WEBHOOK_SECRET!)
  } catch {
    return new Response('Invalid signature', { status: 400 })
  }

  // Only now is it safe to act on event.type
  return new Response('ok', { status: 200 })
}

The raw body matters. Stripe: "Stripe requires the raw body of the request to perform signature verification. If you're using a framework, make sure it doesn't manipulate the raw body. Any manipulation to the raw body of the request causes the verification to fail."

If you verify manually instead of with a library, Stripe adds a detail that's easy to miss: "To protect against timing attacks, use a constant-time-string comparison to compare the expected signature to each of the received signatures."

What about replaying a real event?

A signature stops forged events. A captured real event is a different attack, and Stripe covers it too. "A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them. To mitigate such attacks, Stripe includes a timestamp in the Stripe-Signature header. Because this timestamp is part of the signed payload, it's also verified by the signature, so an attacker can't change the timestamp without invalidating the signature."

The libraries enforce it for you: "Our libraries have a default tolerance of 5 minutes between the timestamp and the current time." Leave that tolerance alone. Stripe warns: "Don't use a tolerance value of 0. Using a tolerance value of 0 disables the recency check entirely."

A second check that a forged event can't pass

Stripe's fulfillment guide already builds in a defense. Its fulfill_checkout function is required to "Retrieve the Checkout Session from the API with the line_items property expanded" and "Check the payment_status property to determine if it requires fulfillment."

That means fulfillment trusts the answer from Stripe's API, called with your secret key, not the contents of the incoming request. A made-up session ID won't come back from the API as paid.

The same applies to the success page. Stripe's guide has the landing page "extract the Checkout Session ID from the URL" and then "Run your fulfill_checkout function with the ID provided", which retrieves and checks the session. A page that grants access just because someone loaded /success?session_id=..., without that lookup, is the same hole in a different place.

Test your own endpoint in one command

Send an unsigned request with an empty JSON body to your own endpoint:

curl -i -X POST \
  -H 'content-type: application/json' \
  -d '{}' \
  https://yourdomain.com/api/webhooks/stripe

400 (or another 4xx from your signature check): good. Unsigned requests are rejected.
200: the endpoint accepts requests without a valid signature. Fix this before anything else.
3xx, 401, 403, 404: something in front of your code answered first (a redirect, an auth wall, a wrong path). That's a separate problem, and it usually means Stripe's real events aren't getting through either.

Only test endpoints you own or are authorized to test.

Checklist

[ ] Every event is verified with the official library (or a constant-time manual check) before any action
[ ] Verification uses the raw request body and the whsec_ secret for this endpoint and this mode
[ ] Signature failures return 400 and do nothing else
[ ] The timestamp tolerance is the default, never 0
[ ] Requests are limited to Stripe's published webhook IP addresses where your host allows it
[ ] Fulfillment retrieves the Checkout Session from the API and checks payment_status
[ ] The success page never grants access from the URL alone

WebhookProof's free checker runs the unsigned-request test above for you: paste a webhook URL and it sends 3 harmless requests to report whether Stripe can reach the endpoint and whether it rejects unsigned events. The full write-up is here: Can someone fake a payment to your app?

WebhookProof is an independent tool, not affiliated with Stripe, Inc. Quotes are from the linked documentation as read on 2026-10-26.

Sources

Stripe, Receive Stripe events in your webhook endpoint (fake-event risk, use both protections, IP allowlisting, signature verification, unique secret per endpoint and mode, raw body, HMAC SHA-256, constant-time comparison, replay attacks, 5-minute default tolerance, don't use 0): https://docs.stripe.com/webhooks
Stripe, IP addresses (webhook source IPs): https://docs.stripe.com/ips
Stripe, Fulfill orders, full-page Checkout (retrieve the Checkout Session, check payment_status, landing page extracts the session ID and runs fulfill_checkout): https://docs.stripe.com/checkout/fulfillment?ui=full-page

Stripe sent the same webhook twice. Make fulfillment idempotent before it costs you

WebhookProof — Fri, 23 Oct 2026 14:06:41 +0000

Signs that something ran twice: a customer gets two welcome emails, two license keys, or a credit balance that doubled. A digital-download store sees two orders in its database for one payment. Nothing failed. Your webhook handler did what it was told, twice.

Stripe documents this behavior. This post covers why one payment can reach your fulfillment code more than once, what to key deduplication on, and a small pattern that holds up even when two calls arrive at the same moment. Every claim links to the doc it comes from (see Sources at the end).

Why the same payment arrives more than once

1. Stripe can redeliver an event. Stripe's webhook docs: "Webhook endpoints might occasionally receive the same event more than once. You can guard against duplicated event receipts by logging the event IDs you've processed, and then not processing already-logged events."

2. Retries are normal. If your endpoint doesn't return 2xx in time, Stripe retries. In live mode it attempts delivery "for up to three days with an exponential back off". A handler that did the work and then timed out before responding will get the same event again. Manual resends add more: "Manually resending an event that failed to reach a webhook endpoint doesn't cancel Stripe's automatic retry behavior, even if it results in a 2xx status code."

3. Sometimes there are two different events. "In some cases, two separate Event objects are generated and sent. To identify these duplicates, use the ID of the object in data.object along with the event.type." An event-ID check alone won't catch that case.

4. Your own success page is a second caller. Stripe's fulfillment guide recommends calling fulfillment both from the webhook and from the Checkout landing page, so the customer gets access right away. It then warns: "your fulfill_checkout function might be called multiple times, possibly concurrently, for the same Checkout Session."

5. Order isn't guaranteed. "Stripe doesn't guarantee the delivery of events in the order that they're generated." Stripe also warns that distinct events can share a timestamp, so "don't use created to determine event order or whether you've already processed an event. Track event IDs to identify duplicate deliveries instead."

What to key on

For one-time purchases through Checkout, Stripe's own requirements for fulfill_checkout give the answer. It must:

"Correctly handle being called multiple times with the same Checkout Session ID."
"Accept a Checkout Session ID as an argument."
"Retrieve the Checkout Session from the API with the line_items property expanded."
"Check the payment_status property to determine if it requires fulfillment."
"Perform fulfillment of the line items."
"Record fulfillment status for the provided Checkout Session."

So the Checkout Session ID is the natural key. It's the same whether the call comes from checkout.session.completed, checkout.session.async_payment_succeeded, a retry, a resend, or the success page. An event ID only dedupes a single event. The session ID dedupes the payment.

Use event IDs as well if you log or process other event types. That's the guard Stripe describes for repeated deliveries.

The pattern: claim first, then fulfill

"Check whether it's done, then do it" has a race: two concurrent calls can both see "not done" and both proceed. Let the database decide instead, with a unique constraint and a single atomic insert.

-- Postgres (works the same on Supabase)
create table fulfillments (
  checkout_session_id text primary key,
  status text not null default 'processing',
  created_at timestamptz not null default now()
);

// Called from the webhook AND the success page
async function fulfillCheckout(sessionId: string) {
  // 1) Try to claim this session. Only one caller can win.
  const claimed = await db.query(
    `insert into fulfillments (checkout_session_id)
     values ($1)
     on conflict (checkout_session_id) do nothing
     returning checkout_session_id`,
    [sessionId],
  )
  if (claimed.rowCount === 0) return // already claimed: do nothing

  // 2) Confirm it's paid, per Stripe's fulfillment guide
  const session = await stripe.checkout.sessions.retrieve(sessionId, {
    expand: ['line_items'],
  })
  if (session.payment_status === 'unpaid') {
    await db.query(`delete from fulfillments where checkout_session_id = $1`, [sessionId])
    return // a later async_payment_succeeded event will call this again
  }

  // 3) Grant access / send the key / write the order
  await grantAccess(session)

  // 4) Record it
  await db.query(
    `update fulfillments set status = 'fulfilled' where checkout_session_id = $1`,
    [sessionId],
  )
}

PostgreSQL's docs describe the key piece: "ON CONFLICT DO NOTHING simply avoids inserting a row as its alternative action," and RETURNING returns values "based on each row actually inserted". If no row comes back, another call already claimed the session.

Two notes on this sketch:

Failures in step 3. If grantAccess throws, the row stays at processing. Either delete the row so a retry can claim it again, or have a cleanup job retry rows stuck in processing. Stripe's own recovery guide uses the same three states (is_processing_or_processed, mark_as_processing, mark_as_processed) for its backlog script.
Duplicates still get 200. When the handler sees a session it already processed, it should return success. Stripe's guide: "When your endpoint receives an event you've already processed, skip it and return a 200 response to stop further retries." Returning an error just brings the event back.

Don't confuse this with `Idempotency-Key`

Stripe's API has idempotency keys, and they solve a different problem: your requests to Stripe. "When creating or updating an object, use an idempotency key. Then, if a connection error occurs, you can safely repeat the request without risk of creating a second object." Keys can be "up to 255 characters long", and for API v1 they can be pruned "after they're at least 24 hours old".

Use them when fulfillment itself calls Stripe, for example to create a refund or a credit. They won't dedupe incoming webhooks. Only your own unique constraint does that.

Keep the handler fast

Many duplicates come from timeouts. Stripe: "Your endpoint must quickly return a successful status code (2xx) before any complex logic that could cause a timeout." For heavy work (PDF generation, sending email, calls to other APIs), Stripe suggests handling events with "an asynchronous queue". Verify the signature, record the session ID, queue the work, and respond. Fewer timeouts mean fewer retries to dedupe.

Checklist

[ ] Fulfillment is keyed on the Checkout Session ID, with a unique constraint in the database
[ ] The claim is a single atomic insert (on conflict do nothing), not a read-then-write
[ ] Webhook and success page call the same function
[ ] payment_status is checked, and checkout.session.async_payment_succeeded is handled for delayed methods
[ ] Already-processed events return 200
[ ] Outbound Stripe writes in fulfillment send an Idempotency-Key
[ ] The handler responds before slow work runs

No outside scan can see whether your fulfillment is idempotent, because it lives in your code and database. WebhookProof's free checker covers the parts that are visible from outside: whether Stripe can reach your endpoint and whether it rejects unsigned events, using 3 harmless requests. The duplicate-event steps are also written up here: Duplicate Stripe webhook events: make fulfillment idempotent.

WebhookProof is an independent tool, not affiliated with Stripe, Inc. Quotes are from the linked documentation as read on 2026-10-18.

Sources

Stripe, Receive Stripe events in your webhook endpoint (duplicate deliveries, two Event objects, ordering, created warning, retries, manual resend doesn't cancel retries, respond with 2xx quickly, async queue): https://docs.stripe.com/webhooks
Stripe, Fulfill orders, hosted Checkout (fulfill_checkout called multiple times and concurrently, six requirements, payment_status, async payment events, landing page plus webhook): https://docs.stripe.com/checkout/fulfillment?payment-ui=stripe-hosted
Stripe, Manage webhook endpoints: process undelivered events (processing/processed states, return 200 for already-processed events): https://docs.stripe.com/webhooks/signature
Stripe API reference, Idempotent requests (outbound idempotency keys, 255 characters, 24-hour pruning): https://docs.stripe.com/api/idempotent_requests
PostgreSQL, INSERT (ON CONFLICT DO NOTHING, RETURNING): https://www.postgresql.org/docs/current/sql-insert.html

Stripe webhooks broke the day you went live? Check which whsec_ you're using

WebhookProof — Wed, 21 Oct 2026 14:06:22 +0000

Everything passed in test mode. You switched to live keys, made a real purchase, and the webhook started failing. Stripe's delivery log shows 400 on every event, and your logs say:

No signatures found matching the expected signature for payload.

Your code didn't change. The secret did, or rather it should have and didn't. This post covers why each Stripe endpoint and mode has its own signing secret, the three secrets that usually get mixed up, and how to swap the right one in without dropping events. Every claim links to the doc it comes from (see Sources at the end).

One endpoint, one mode, one secret

Stripe's webhook docs: "Stripe generates a unique secret key for each endpoint. If you use the same endpoint for both test and live API keys, the secret is different for each one. Additionally, if you use multiple endpoints, you must obtain a secret for each one you want to verify signatures on."

Stripe's API keys page also notes that webhook secrets aren't API keys: "Webhook signing secrets aren't API keys—they're per-webhook secrets that your webhook receiver uses to authenticate that webhooks actually came from Stripe."

So changing sk_test_ to sk_live_ doesn't touch your whsec_ value at all. Stripe's go-live steps list it as its own step: "If you use webhooks, update each webhook endpoint's URL and copy the new signing secret from the Webhooks section of the Dashboard."

Why the error looks like this

Stripe signs every event with an HMAC-SHA256 of the timestamp and the raw body, keyed with that endpoint's secret. Your library recomputes the HMAC with the secret you give it and compares the two. With the wrong secret the HMACs can never match, so the library raises the generic error above.

Stripe's troubleshooting page says that if you see it, "at least one of the three parameters you passed is incorrect": the raw body, the Stripe-Signature header, or the endpoint secret. It also names the usual suspect: "The most common cause is using the wrong endpoint secret."

The three secrets that get mixed up

All three start with whsec_, which is why it's easy to mix them up.

The stripe listen secret. The CLI prints its own: "Ready! Your webhook signing secret is '...'". Stripe's troubleshooting page: "The secret for a CLI-forwarded endpoint is different from the secret for a Dashboard-managed endpoint—don't mix them up." It belongs in .env.local, not in production.
The test-mode (sandbox) endpoint secret. It verifies sandbox events only. Stripe: "Each mode has its own set of API keys, and objects in one mode aren't accessible to the other."
The live endpoint secret. Shown on the live-mode endpoint in Workbench → Webhooks → Reveal secret. This is the only one that verifies live events.

A fourth situation catches teams with more than one endpoint, such as staging and production, or two separate handlers. Each endpoint has its own secret, so copying one endpoint's secret into the other endpoint's environment fails the same way.

How to tell which one you have

Don't print the secret to your logs. Compare it by eye instead:

In Stripe, switch to live mode, open Workbench → Webhooks, select the endpoint whose URL matches your production handler, and click Reveal secret.
In your host's environment settings, open the production value of STRIPE_WEBHOOK_SECRET (or whatever your code reads) and compare the first and last few characters.
Check that the code reads the variable you think it does. A fallback like process.env.STRIPE_WEBHOOK_SECRET ?? 'whsec_...' holding a hardcoded test secret causes the same failure. Stripe's key guidance applies here too: "Don't put keys in source code or configuration files checked into version control."

Some quick tells in the Stripe delivery log:

Live events fail with 400, test events pass → live endpoint, test secret.
Nothing fails in Stripe, but production events never show up → there may be no live endpoint yet. Stripe keeps sandbox and live objects apart, so an endpoint created in a sandbox won't receive live events. Create one in live mode.
Failures began right after "Roll secret" → the old secret expired before your server got the new one (see below).

Swapping the secret without losing events

Update the variable, then make sure the running code sees it. On Vercel: "Any change you make to environment variables are not applied to previous deployments, they only apply to new deployments." Redeploy production after you change the variable. On Supabase Edge Functions, supabase secrets set STRIPE_WEBHOOK_SIGNING_SECRET=whsec_... takes effect without a redeploy, per Supabase's secrets docs.

When rolling a secret, use the overlap window. Stripe lets you "delay its expiration for up to 24 hours to allow yourself time to update the verification code on your server. During this time, multiple secrets are active for the endpoint. Stripe generates one signature per secret until expiration." Deploy the new secret within that window and nothing fails.

Recover what failed. In live mode Stripe retries failed deliveries "for up to three days with an exponential back off". Anything older, or anything you want handled now, can be resent from the Dashboard "for up to 15 days after the event creation", or with stripe events resend for up to 30 days. Stripe makes "a new signature and timestamp for the new delivery attempt", so resent events verify against the new secret.

Don't fix it by turning verification off

When this error shows up on launch day, it's tempting to comment out the signature check "for now". Stripe's docs explain the cost: "Without verification, an attacker could send fake webhook events to your endpoint to trigger actions like fulfilling orders, granting account access, or modifying records." Keep returning 400 when verification fails, as Stripe's own examples do, and fix the secret.

Go-live checklist

[ ] A live-mode endpoint exists for the production URL, subscribed to the events you handle
[ ] Production STRIPE_WEBHOOK_SECRET = that live endpoint's whsec_ (not the sandbox one, not stripe listen's)
[ ] One secret per endpoint: staging and production don't share
[ ] No hardcoded fallback secret in code
[ ] Redeployed after changing the variable (Vercel), or set with supabase secrets set
[ ] A resent live event shows 200

WebhookProof's free checker can't see your secret, and no outside scan can. It does confirm the half of the problem that's visible from outside: whether Stripe can reach your live endpoint and whether that endpoint rejects unsigned events, using 3 harmless requests. The go-live steps above are also in the guide: Test vs live Stripe webhook secret.

WebhookProof is an independent tool, not affiliated with Stripe, Inc. Quotes are from the linked documentation as read on 2026-10-18.

Sources

Stripe, Receive Stripe events in your webhook endpoint (secret per endpoint and per mode, stripe listen secret, HMAC-SHA256 signing, rolling secrets and the 24-hour overlap, retries, resend windows, new signature per retry, why to verify): https://docs.stripe.com/webhooks
Stripe, Manage webhook endpoints: resolve signature verification errors (the error text, "at least one of the three parameters", wrong secret most common, CLI vs Dashboard secret): https://docs.stripe.com/webhooks/signature
Stripe, API keys (signing secrets aren't API keys, sandbox vs live mode, go-live: copy each endpoint's new signing secret, don't commit keys): https://docs.stripe.com/keys
Vercel, Environment variables (changes apply only to new deployments): https://vercel.com/docs/environment-variables
Supabase, Environment variables / secrets (supabase secrets set, no redeploy needed): https://supabase.com/docs/guides/functions/secrets

Customer paid in your Lovable or Bolt app but nothing unlocked? Where to look first

WebhookProof — Mon, 19 Oct 2026 11:53:09 +0000

A customer writes in: they paid, and they still can't get in. Stripe shows a successful payment. Your app shows a locked screen.

In apps built with Lovable or Bolt, the fix depends on how the builder connected Stripe, because the two take different routes. This post covers how each one decides a customer has paid, where that breaks, and what to paste back into the builder. Every claim links to the doc it comes from (see Sources at the end).

Step 0: find out which setup you have

Lovable offers two routes. Its docs say "most projects should use built-in payments", where "Lovable provisions the Stripe or Paddle account and manages keys, webhooks, and test and live environments for you." The other route is "Connect your own Stripe account", where you supply the API key. A project "can use one or the other, not both at the same time."

Bolt has a single Stripe integration that "requires Supabase as your database provider". When you apply it, Bolt "automatically creates the Supabase edge functions to handle" checkout session creation, "payment webhook processing", and subscription management.

If you're on Lovable built-in payments, Lovable runs the webhook side, so start in its Payments view. The rest of this post is about the setups where the payment wiring sits in your project: Lovable with your own Stripe account, and Bolt.

Lovable with your own Stripe account: no webhooks by default

Lovable's docs are explicit: "By default, the integration does not use webhooks: your app checks payment and subscription status directly with Stripe."

That gives two common failure modes.

1. One-time purchases granted only on the success page

For a one-time purchase, the buyer pays in Stripe Checkout and then "returns to a payment success page in your app". If the code that grants access only runs when that page loads, a buyer who closes the tab never gets access.

Stripe warns about exactly this: "You can't rely on triggering fulfillment only from your checkout landing page, because it's not guaranteed customers visit that page. For example, a customer can pay successfully and then lose their internet connection before your landing page loads." Stripe's fix is a webhook that calls the same fulfillment function, with the landing page as a second, faster path.

Lovable supports that when you ask for it. It "writes the webhook function, and you finish the setup in your Stripe dashboard": create an event destination for the function's URL, choose the events, and add the signing secret when Lovable asks.

Prompt to paste into Lovable:

Add a Stripe webhook function that handles checkout.session.completed and checkout.session.async_payment_succeeded, verifies the Stripe-Signature header against the signing secret, and grants access through the same function the success page uses. Make that function safe to run twice for the same Checkout Session ID.

2. Subscriptions matched by email

For subscriptions, "subscriptions are matched to users by email address. A user's subscription is recognized when the email they sign in with matches the email on their Stripe customer record." If a customer pays as jane@work.com and logs in as jane@gmail.com, the check finds no subscription.

Check: in Stripe, open the customer record and compare its email with the one the user signs in with. If they differ, change one of them, or ask Lovable to link the Stripe customer ID to the user at checkout rather than relying on the email match.

Bolt: the webhook function exists, so check that it runs

Bolt's docs say it "automatically handles webhook endpoint registration and signature verification. You don't need to manually configure webhook endpoints in your Stripe dashboard." With the plumbing generated for you, the useful question is whether events are actually arriving and succeeding.

Check: in Stripe, open Workbench → Webhooks, select the endpoint, and open Event deliveries. Stripe's docs say this tab lists each event as Delivered, Pending or Failed, along with "the HTTP status code of the delivery attempt".

Then work from the status code.

Reading the status code (both builders)

These apply whenever your webhook is a Supabase Edge Function, which is how Bolt builds it, and how Lovable builds it on your own Supabase project.

401 with "Missing authorization header" or "Invalid Token...": Supabase's troubleshooting guide says these messages "come from the legacy auth verification check", which "runs before your code. When it fails, your function never executes." Stripe sends no Supabase token, so the platform rejects the event. Fix: turn off JWT verification for the webhook function only, then verify the Stripe signature inside it.

The Stripe webhook Edge Function returns 401 before it runs. Set verify_jwt = false for that function only in supabase/config.toml, keep Stripe signature verification with constructEventAsync on the raw body (await req.text()), and redeploy.

400 with a signature error: the function runs but the signature doesn't match. The most common cause, per Stripe, is "using the wrong endpoint secret", for example a test secret on the live endpoint (next section).

200, but still no access: the event arrived and your function returned success without granting access. Check that the endpoint subscribes to the event your code handles (checkout.session.completed for one-time payments), and look in the function logs for the database write.

No delivery at all: the live-mode endpoint may not exist, or may not subscribe to that event type.

Test vs live: the go-live trap

Both builders tell you to start with test keys. Bolt: "Use test keys for development. Test keys start with sk_test_." Stripe's docs explain why switching modes takes more than a new key: "Each mode has its own set of API keys, and objects in one mode aren't accessible to the other." Webhook secrets differ too: "If you use the same endpoint for both test and live API keys, the secret is different for each one."

Lovable's go-live steps cover the price side: "Price IDs differ between test and live mode, so ask Lovable to switch your app to the live price IDs." If you added a webhook, also paste in the live endpoint's whsec_ secret. The test one won't verify live events.

Fixing customers who already paid

Once the endpoint works, recover the missed events. Stripe's docs say a Dashboard Resend works "for up to 15 days after the event creation", and the CLI's stripe events resend works for 30. In live mode Stripe also retries failed events "for up to three days". Make sure the grant is safe to run twice before you resend, because Stripe says your fulfillment function "might be called multiple times, possibly concurrently, for the same Checkout Session."

Checklist

[ ] Know which route you're on: Lovable built-in, Lovable with your own Stripe, or Bolt
[ ] Access is granted from a webhook, not only from the success page
[ ] Subscriptions: the login email matches the Stripe customer email (or you match on customer ID)
[ ] Event deliveries show 200, not 401 or 400
[ ] Live mode: live key, live price IDs, live endpoint, live whsec_
[ ] Granting access twice for the same Checkout Session does nothing extra

WebhookProof's free checker sends 3 harmless requests to your webhook URL and tells you whether Stripe can reach it (401s, redirects, login walls) and whether it accepts unsigned events. Each issue comes with a prompt to paste into your builder. More detail in the guide: Stripe webhooks with Supabase, Lovable and Bolt.

WebhookProof is an independent tool, not affiliated with Stripe, Inc., Lovable, Bolt or Supabase, Inc. Quotes are from the linked documentation as read on 2026-10-18.

Sources

Lovable, Connect your own Stripe account (built-in vs own account, no webhooks by default, success page, email matching, webhook setup, live price IDs): https://docs.lovable.dev/integrations/stripe
Bolt, Stripe for payments (Supabase requirement, auto-created edge functions, automatic webhook registration and verification, sk_test_ keys): https://support.bolt.new/integrations/stripe
Stripe, Fulfill orders, hosted Checkout (don't rely on the landing page, fulfill_checkout may be called multiple times, async payment events): https://docs.stripe.com/checkout/fulfillment?payment-ui=stripe-hosted
Stripe, Receive Stripe events in your webhook endpoint (Event deliveries tab, per-mode secrets, retries, resend windows): https://docs.stripe.com/webhooks
Stripe, Manage webhook endpoints (wrong endpoint secret is the most common signature error): https://docs.stripe.com/webhooks/signature
Stripe, API keys (sandbox vs live mode, objects not shared across modes): https://docs.stripe.com/keys
Supabase, Edge Function 401 error response (legacy JWT check runs before your code): https://supabase.com/docs/guides/troubleshooting/edge-function-401-error-response
Supabase, Function Configuration (verify_jwt = false per function): https://supabase.com/docs/guides/functions/function-configuration

Stripe webhook shows 307 or 308 on Vercel / Next.js? It's a redirect, and Stripe won't follow it

WebhookProof — Mon, 19 Oct 2026 03:57:37 +0000

The checkout works and the money arrives, but your app never finds out. Open the webhook endpoint in Stripe and every delivery attempt says 307 or 308. Your route handler logs are empty.

That's not a bug in your handler. Something in front of it answered with a redirect, and Stripe doesn't follow redirects. This post covers where those redirects come from on Next.js and Vercel, how to find the exact URL Stripe should call, and how to check the fix. Every claim links to the doc it comes from (see Sources at the end).

Why a redirect counts as a failure

Stripe's webhook docs list this under delivery errors: "302 ERR (or other 3xx status)... The destination server attempted to redirect the request to another location. We consider redirect responses to webhook requests as failures." Stripe's recommended fix is short: "Set the webhook endpoint destination to the URL resolved by the redirect."

In other words, don't fight the redirect. Find where it ends up, and register that URL.

The same docs say a registered endpoint must be a "publicly accessible HTTPS URL", and in live mode Stripe retries a failed event "for up to three days with an exponential back off". So a redirect doesn't lose the event right away, but every retry hits the same redirect until the URL is corrected.

Why 307 and 308 specifically

Next.js explains its choice in the redirects reference. Older 301/302 redirects let many browsers switch a POST to a GET, so "Next.js uses the 307 temporary redirect, and 308 permanent redirect status codes to explicitly preserve the request method used." Vercel's redirect docs recommend 307 or 308 for the same reason.

When you see a 307 or 308 in Stripe's delivery log, the response came from a Next.js or Vercel redirect rule, not from your code. There are four usual sources.

Cause 1: the trailing slash

From the Next.js trailingSlash docs: "By default Next.js will redirect URLs with trailing slashes to their counterpart without a trailing slash. For example /about/ will redirect to /about." If you set trailingSlash: true, it works the other way round.

The skipTrailingSlashRedirect reference spells out the status codes:

`trailingSlash`	Request	Response
`false` (default)	`/api/webhooks/stripe/`	`308` to `/api/webhooks/stripe`
`true`	`/api/webhooks/stripe`	`308` to `/api/webhooks/stripe/`

Fix: copy the endpoint URL from Stripe, compare the end of it with your trailingSlash setting, and edit the endpoint URL to match. You don't need to change your Next.js config for this.

Cause 2: apex vs www (domain redirect)

Vercel's domain docs say that if a visitor uses your domain with or without www, Vercel "will attempt to redirect automatically", and you can also add the redirect yourself under Domains in Project Settings. Vercel recommends "using the www subdomain as your primary domain, with a redirect from the non-www domain to it."

So if your project's primary domain is www.example.com and the Stripe endpoint says https://example.com/api/webhooks/stripe, every delivery gets redirected before it reaches your function. The reverse happens if apex is primary and Stripe has the www URL.

Fix: in Vercel, open Project Settings → Domains and see which domain is primary and which one redirects. Put the primary host in the Stripe endpoint URL.

Cause 3: a `redirects()` rule that matches the webhook path

In the redirects reference, permanent: true "will use the 308 status code" and permanent: false "will use the 307 status code". Redirects are also "checked before the filesystem", so a wide rule beats your route handler. A catch-all like source: '/:path*' that moves traffic to a new domain or locale will catch /api/webhooks/stripe too.

The same goes for redirects in vercel.json, and for Vercel Firewall redirects. Vercel says a dashboard firewall redirect "creates a temporary 307 redirect", and that firewall redirects run "before CDN configuration redirects".

Fix: narrow the rule so it skips the webhook path, or point Stripe at the destination the rule sends traffic to.

Cause 4: Proxy (formerly Middleware) redirecting to login

Next.js renamed middleware to proxy in v16. Its docs say it's commonly used "for implementing custom server-side logic like authentication", and that "without a matcher, Proxy runs on every request". Auth middleware that sends logged-out visitors to /login with NextResponse.redirect(...) treats Stripe as a logged-out visitor. Stripe has no session cookie, so it gets redirected.

The docs' own negative-matcher example leaves out api:

// proxy.ts (or middleware.ts on Next.js 15 and earlier)
export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)'],
}

Fix: exclude the webhook route from the matcher, or return early for that path. In either case, the handler itself still has to verify the Stripe-Signature header, as Stripe's docs require.

One more: double slashes

Vercel's CDN "normalizes URLs containing consecutive slashes (e.g., //) to single slashes and redirects with a 308 status code." An endpoint pasted as https://www.example.com//api/webhooks/stripe fails for that reason alone.

How to find the real URL

curl shows the redirect and where it points. Send a POST, since that's what Stripe sends:

curl -i -X POST -H 'content-type: application/json' -d '{}' \
  https://example.com/api/webhooks/stripe/

If the first line is HTTP/2 307 or HTTP/2 308, the location: header is where the request is meant to go. Run the command again against that URL, and repeat until the response is no longer a 3xx. Vercel's redirect docs use the same method (curl -I and look for the Location).

When you reach the final URL, an unsigned POST like the one above should get a 400, because your handler rejected a request with no valid signature. If it gets a 200, your endpoint accepts unsigned events, which is a separate and worse problem.

Then:

Edit the endpoint in Stripe (Workbench → Webhooks) and paste the final URL.
Open a failed event and click Resend. Stripe's docs say Dashboard resends work "for up to 15 days after the event creation" (or 30 days with stripe events resend in the CLI).
Check that the event delivery now shows 200.

The same mistake can happen locally. If stripe listen --forward-to localhost:3000/api/webhooks/stripe/ uses a trailing slash your app redirects away from, the CLI shows the same 308.

Checklist

[ ] Host in the Stripe endpoint = the primary domain in Vercel (apex vs www)
[ ] Trailing slash in the Stripe endpoint matches trailingSlash in next.config.js
[ ] No redirects(), vercel.json or Firewall rule matches the webhook path
[ ] Proxy/Middleware matcher excludes the webhook route
[ ] curl -i -X POST to the registered URL returns a non-3xx (ideally 400 for an unsigned request)
[ ] A resent event shows 200 in Event deliveries

If you'd rather not follow redirects by hand, WebhookProof's free checker sends 3 harmless requests to your webhook URL and reports redirects, auth walls, and whether the endpoint accepts unsigned events. The guide for this case is here: Stripe webhook 307 / 308 redirect error (Vercel, Next.js).

WebhookProof is an independent tool, not affiliated with Stripe, Inc. or Vercel Inc. Quotes are from the linked documentation as read on 2026-10-18.

Sources

Stripe, Receive Stripe events in your webhook endpoint (3xx counted as failures, "URL resolved by the redirect", public HTTPS, retries, resend windows, signature verification): https://docs.stripe.com/webhooks
Next.js, trailingSlash (default redirect behavior): https://nextjs.org/docs/app/api-reference/config/next-config-js/trailingSlash
Next.js, skipTrailingSlashRedirect (308 status table): https://nextjs.org/docs/app/api-reference/config/next-config-js/skipTrailingSlashRedirect
Next.js, redirects (permanent → 308/307, why 307/308, checked before the filesystem): https://nextjs.org/docs/app/api-reference/config/next-config-js/redirects
Next.js, proxy.js file convention (rename from middleware in v16, matcher behavior, negative matcher example): https://nextjs.org/docs/app/api-reference/file-conventions/proxy
Vercel, Deploying & Redirecting Domains (automatic www/apex redirect, www recommended as primary): https://vercel.com/docs/domains/working-with-domains/deploying-and-redirecting
Vercel, Redirects (307/308 recommendation, firewall 307, double-slash 308 normalization, curl verification): https://vercel.com/docs/redirects

Stripe webhook returns 401 on a Supabase Edge Function? Here's the fix (and the step after it)

WebhookProof — Sun, 18 Oct 2026 23:56:07 +0000

Checkout works. The customer pays. Stripe's delivery log for your webhook shows 401 on every attempt, and your Edge Function logs show nothing at all.

That combination is almost always Supabase's built-in JWT check, not your Stripe code. This post covers why it happens, how to turn it off for the webhook function only, and the step you must take right after, because once the function is public, the Stripe signature is the only thing protecting it. Every claim links to the doc it comes from (see Sources at the end).

What the 401 looks like

Open the endpoint in the Stripe Dashboard and look at a failed delivery. If the response body is one of these, the request never reached your handler:

{ "code": 401, "message": "Missing authorization header" }

{ "code": 401, "message": "Invalid Token or Protected Header formatting" }

Supabase's troubleshooting guide says both messages "come from the legacy auth verification check", which "runs before your code. When it fails, your function never executes." If the body is a message you wrote yourself (or empty), your own code returned the 401 and you should look there instead.

Stripe's side agrees: its webhook docs list 4xx responses, including 401 and 403 "when the destination URL has access restrictions", as failed deliveries, and ask that your endpoint be "publicly accessible to the internet".

Why it happens

Supabase's function configuration docs: "By default, Edge Functions require a valid JWT in the authorization header." Stripe sends a Stripe-Signature header and a JSON body. It has no Supabase user token, so the platform rejects it with a 401 before Deno.serve (or your exported fetch) ever runs.

Supabase calls this out directly: "Stripe webhooks need to be publicly accessible (Stripe doesn't have your user tokens)."

Fix 1: turn off JWT verification for the webhook function only

In `config.toml` (sticks across deploys)

This is the exact example in Supabase's function configuration docs:

# supabase/config.toml
# Disables authentication for the Stripe webhook.
[functions.stripe-webhook]
verify_jwt = false

The key after functions. is your function's name. Leave every other function on the default.

On the CLI

The supabase functions deploy reference lists --no-verify-jwt ("Disable JWT verification for the Function"), and Supabase's own Stripe example deploys with it:

supabase functions deploy stripe-webhook --no-verify-jwt

For local testing, the same flag works on serve, and the example pairs it with stripe listen:

# terminal 1
supabase functions serve --no-verify-jwt --env-file ./supabase/.env.local
# terminal 2
stripe listen --forward-to localhost:54321/functions/v1/stripe-webhook

In the Dashboard

Supabase's 401 troubleshooting guide also lists a Dashboard route: open the function's detail tab and toggle off JWT verification. If your function gets redeployed by a tool (an AI app builder, a CI job), put the setting in config.toml as well so a redeploy doesn't quietly turn it back on. Users have reported exactly that in a Supabase CLI issue (linked below), where "Enforce JWT verification" was enabled again after a push.

Fix 2: verify the Stripe signature, the Deno way

Supabase's docs carry a warning with the flag: it "will allow anyone to invoke your Edge Function without a valid JWT." Your webhook URL is now public. If the handler trusts the JSON body, anyone who knows the URL can POST a hand-written checkout.session.completed and unlock your product.

Supabase's "Securing Edge Functions" page says the same for external webhooks: providers like Stripe "sign the request body with their own shared secret", so skip the credential check, "then verify the provider's signature inside the handler. Keep verify_jwt = false."

Two details matter in Deno:

Use the raw body. Stripe: "Stripe requires the raw body of the request to perform signature verification... Any manipulation to the raw body of the request causes the verification to fail." Read it with await req.text(). Don't call req.json() first.
Use the async verifier with a Web Crypto provider. stripe-node's SubtleCryptoProvider "only supports asynchronous operations". Its synchronous path throws SubtleCryptoProvider cannot be used in a synchronous context. So use constructEventAsync with Stripe.createSubtleCryptoProvider(), not constructEvent.

This is the shape of Supabase's official Stripe webhook example:

// supabase/functions/stripe-webhook/index.ts
import Stripe from 'npm:stripe@^22'
import { withSupabase } from 'npm:@supabase/server@^1'

const stripe = new Stripe(Deno.env.get('STRIPE_API_KEY') as string)
// Needed to use the Web Crypto API in Deno
const cryptoProvider = Stripe.createSubtleCryptoProvider()

// Stripe verifies the request via its signature, so deploy with verify_jwt = false.
export default {
  fetch: withSupabase({ auth: 'none' }, async (req) => {
    const signature = req.headers.get('Stripe-Signature')
    const body = await req.text() // raw body, not req.json()

    let event
    try {
      event = await stripe.webhooks.constructEventAsync(
        body,
        signature!,
        Deno.env.get('STRIPE_WEBHOOK_SIGNING_SECRET')!,
        undefined,
        cryptoProvider,
      )
    } catch (err) {
      return new Response((err as Error).message, { status: 400 })
    }

    // handle event.type here (e.g. checkout.session.completed)
    return Response.json({ ok: true })
  }),
}

If you're on a plain Deno.serve(async (req) => { ... }) handler instead of the withSupabase wrapper, the three lines that matter are the same: await req.text(), constructEventAsync(...) with cryptoProvider, and a 400 when it throws.

Fix 3: the right signing secret for the right endpoint

A 401 that turns into a 400 after Fix 1 usually means your code is now running but the signature doesn't match. Check which whsec_ value the function has.

From Stripe's webhook docs: "Stripe generates a unique secret key for each endpoint. If you use the same endpoint for both test and live API keys, the secret is different for each one. Additionally, if you use multiple endpoints, you must obtain a secret for each one." The stripe listen command prints its own signing secret too ("Your webhook signing secret is ..."), which is for local forwarding, not your deployed endpoint.

Set the secret for the deployed function with the Supabase CLI (or under Edge Function Secrets in the Dashboard):

supabase secrets set STRIPE_WEBHOOK_SIGNING_SECRET=whsec_...

Supabase's secrets docs note that functions "read a new secret immediately, so you don't need to redeploy." When you go live, swap in the live endpoint's secret. The test one won't verify live events.

How to check

Two curl calls tell you most of what you need. Replace the URL with your function's (https://<project-ref>.supabase.co/functions/v1/<name>).

# 1) Unsigned POST, no Authorization header (this is what Stripe "looks like" to the platform)
curl -i -X POST -H 'content-type: application/json' -d '{}' \
  https://<project-ref>.supabase.co/functions/v1/stripe-webhook

401 with "Missing authorization header": JWT verification is still on. Go back to Fix 1.
400 (with the official example, stripe-node's message is No stripe-signature header value was provided.): good. The function is reachable and rejects unsigned events.
200: the function is reachable but accepts unsigned events. Go to Fix 2 now.

Then, in the Stripe Dashboard, resend a failed event and confirm the delivery shows a 2xx. Stripe's docs say Dashboard resends work "for up to 15 days after the event creation", and in live mode Stripe itself keeps retrying for up to three days.

If you'd rather not run the curls by hand, WebhookProof's free checker runs the reachability and unsigned-event checks against your URL with 3 harmless requests: Stripe webhooks on Supabase Edge Functions: 401s and signature errors.

Checklist

[ ] verify_jwt = false for the webhook function only, in supabase/config.toml (and/or deployed with --no-verify-jwt)
[ ] Handler reads await req.text() before anything else touches the body
[ ] Verification uses constructEventAsync + Stripe.createSubtleCryptoProvider() and returns 400 on failure
[ ] STRIPE_WEBHOOK_SIGNING_SECRET is the whsec_ for this endpoint in this mode (not the stripe listen one in production)
[ ] An unsigned curl gets 400, and a resent Dashboard event gets 2xx

WebhookProof is an independent tool, not affiliated with Stripe, Inc. or Supabase, Inc. Quotes are from the linked documentation as read on 2026-10-18.

Sources

Supabase, Function Configuration (default JWT requirement, verify_jwt = false example for stripe-webhook, --no-verify-jwt caution): https://supabase.com/docs/guides/functions/function-configuration
Supabase, Edge Function 401 error response (error bodies, "runs before your code", Dashboard / CLI / Management API fixes): https://supabase.com/docs/guides/troubleshooting/edge-function-401-error-response
Supabase, Securing Edge Functions (external webhooks: auth: 'none', verify signature, keep verify_jwt = false): https://supabase.com/docs/guides/functions/auth
Supabase, Handling Stripe Webhooks example: https://supabase.com/docs/guides/functions/examples/stripe-webhooks
Supabase example source (constructEventAsync, createSubtleCryptoProvider, req.text()): https://github.com/supabase/supabase/blob/master/examples/edge-functions/supabase/functions/stripe-webhooks/index.ts
Supabase example README (serve --no-verify-jwt, deploy --no-verify-jwt, stripe listen): https://github.com/supabase/supabase/blob/master/examples/edge-functions/supabase/functions/stripe-webhooks/README.md
Supabase CLI reference, supabase functions deploy (--no-verify-jwt flag): https://supabase.com/docs/reference/cli/supabase-functions-deploy
Supabase, Environment variables / secrets (supabase secrets set, no redeploy needed): https://supabase.com/docs/guides/functions/secrets
Supabase CLI issue #3397 (users reporting verify_jwt = false not applied / JWT enforcement re-enabled after a push): https://github.com/supabase/cli/issues/3397
Stripe, Receive Stripe events in your webhook endpoint (raw body, per-endpoint and per-mode secrets, 4xx delivery errors, retries, resend window): https://docs.stripe.com/webhooks
stripe-node, SubtleCryptoProvider source (async-only): https://github.com/stripe/stripe-node/blob/master/src/crypto/SubtleCryptoProvider.ts
stripe-node, Webhooks.ts source (error messages): https://github.com/stripe/stripe-node/blob/master/src/Webhooks.ts

Customer paid but didn't get access? 4 reasons your Stripe webhook is silently failing

WebhookProof — Sun, 18 Oct 2026 23:38:57 +0000

A customer emails you: "I paid, but I still can't log in." Stripe shows a successful payment. Your app shows nothing. No exception, no log line. The webhook that should have unlocked their account either never arrived or arrived and was handled wrong.

Below are the four most common causes, how to confirm each one, and a short fix for Node/Next.js and Supabase. Every claim links to the docs it comes from.

If you'd rather check first and read later, WebhookProof is a free tool that sends your webhook URL 3 harmless requests and tells you whether Stripe can reach it and whether it rejects unsigned events. (Not affiliated with Stripe, Inc.)

Before anything: read the delivery log

In the Stripe Dashboard, open your webhook endpoint and look at its event deliveries. Each attempt records the HTTP status your server returned, and that status usually points straight at one of the causes below:

Status in the log	Most likely cause
301 / 302 / 307 / 308	#1 Redirect
401 / 403	#2 Auth wall
200, but anyone can trigger it	#3 No signature verification
400 "No signatures found matching the expected signature"	#4 Body was parsed before verification

Stripe documents these delivery errors on its Receive events / webhooks page.

1. The endpoint redirects (www, https, trailing slash)

Stripe does not follow redirects on webhook deliveries. From the Stripe webhooks docs:

We consider redirect responses to webhook requests as failures. Set the webhook endpoint destination to the URL resolved by the redirect.

Common sources of a surprise redirect:

Apex vs www. Vercel lets you redirect between example.com and www.example.com (Vercel docs). If Stripe is pointed at the non-canonical host, every event bounces.
Trailing slash. "By default Next.js will redirect URLs with trailing slashes to their counterpart without a trailing slash" (Next.js trailingSlash docs). So /api/webhooks/stripe/ gets a redirect. With trailingSlash: true it's the reverse.
Redirect rules. In Next.js redirects(), permanent: true returns 308 and permanent: false returns 307 (Next.js redirects docs). A broad rule can catch your webhook path.
http to https. Always register the https URL.

Confirm it:

curl -i -X POST https://example.com/api/webhooks/stripe

If the response is a 3xx with a location: header, that header is your real URL.

Fix: paste the exact final URL (host, scheme, slash and all) into the endpoint settings in the Dashboard, then resend a failed event from the Dashboard. Don't try to "fix" it by adding more redirects.

2. An auth wall is asking Stripe to log in

Stripe can't send a session cookie, a Supabase JWT or a Vercel login. If anything in front of your handler requires one, Stripe gets a 401/403 and your code never runs.

Supabase Edge Functions: JWT verification

Edge Functions check for a Supabase JWT by default. Supabase's own Stripe webhook example says: "Stripe verifies the request via its signature, so deploy with verify_jwt = false." The function configuration docs show how to do it for just that function:

# supabase/config.toml
[functions.stripe-webhook]
verify_jwt = false

That makes the function publicly callable, which is exactly why cause #3 (signature verification) is not optional.

Vercel Deployment Protection

If Deployment Protection covers the URL Stripe calls (often a preview or *.vercel.app URL), Stripe hits a login wall. The simplest fix is to point Stripe at your production domain. If you really need a protected deployment to receive webhooks, Vercel's Protection Bypass for Automation supports an x-vercel-protection-bypass query parameter, and the docs name Stripe as a case for it:

https://your-deployment.vercel.app/api/webhooks/stripe?x-vercel-protection-bypass=YOUR_SECRET

Your own middleware / proxy

Auth middleware that runs on every route will run on your webhook route too. Without a matcher, Next.js "Proxy runs on every request" (Next.js proxy docs; middleware has been renamed to proxy, same idea). Exclude the webhook path:

// proxy.ts (or middleware.ts on older Next.js)
export const config = {
  matcher: ['/((?!api/webhooks/stripe|_next/static|_next/image|favicon.ico).*)'],
};

Same idea in Express: register the webhook route before your auth middleware, or skip that path in it.

3. No signature verification: anyone can fake a payment

This one doesn't show up as a failure at all, which is what makes it dangerous. If your handler does something like this:

// Don't do this
const event = await req.json();
if (event.type === 'checkout.session.completed') grantAccess(event.data.object);

then anyone who knows the URL can POST a hand-written checkout.session.completed and unlock your product. Webhook paths are predictable (/api/webhooks/stripe is in half the tutorials out there), so treat the URL as public.

Stripe signs every event with the endpoint's secret in the Stripe-Signature header and tells you to verify it with the official library (Stripe docs: verify events). The signed payload includes a timestamp, and "our libraries have a default tolerance of 5 minutes between the timestamp and the current time," which limits replays (Stripe webhooks docs).

Two extra guards worth adding:

Re-check with the API before granting access. Stripe's fulfillment guide retrieves the Checkout Session and checks payment_status isn't unpaid. A forged event can't fake the API's answer.
Make fulfillment idempotent. The same guide warns your fulfill function "might be called multiple times, possibly concurrently, for the same Checkout Session."

async function fulfill(sessionId: string) {
  const session = await stripe.checkout.sessions.retrieve(sessionId);
  if (session.payment_status === 'unpaid') return;
  // Use a unique constraint on session.id so a second call is a no-op
  await db.grantAccessOnce(session.id, session.customer_details?.email);
}

Also watch the secret itself: "if you use the same endpoint for both test and live API keys, the secret is different for each one" (Stripe webhooks docs). Shipping to production with the test whsec_ (or the stripe listen secret) makes every live event fail verification.

Confirm it: send an unsigned request to your own endpoint.

curl -i -X POST -H 'content-type: application/json' -d '{}' \
  https://example.com/api/webhooks/stripe

A correctly protected endpoint answers 400. A 200 means it accepts unsigned events.

4. Your framework parsed the body before you verified it

From the Stripe webhooks docs:

Stripe requires the raw body of the request to perform signature verification. If you're using a framework, make sure it doesn't manipulate the raw body. Any manipulation to the raw body of the request causes the verification to fail.

Parsing JSON and stringifying it again changes whitespace and key order, so the signature no longer matches. The Node library then throws "No signatures found matching the expected signature for payload." The tempting "fix" is deleting the check, which takes you straight back to cause #3.

Next.js App Router

Read the body as text and pass that exact string in. Don't call req.json() first. Route handlers give you a standard Request:

// app/api/webhooks/stripe/route.ts
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(req: Request) {
  const body = await req.text();                      // raw body
  const signature = req.headers.get('stripe-signature') ?? '';

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(body, signature, process.env.STRIPE_WEBHOOK_SECRET!);
  } catch {
    return new Response('Invalid signature', { status: 400 });
  }

  if (
    event.type === 'checkout.session.completed' ||
    event.type === 'checkout.session.async_payment_succeeded'
  ) {
    await fulfill((event.data.object as Stripe.Checkout.Session).id);
  }

  return new Response(null, { status: 200 });
}

Those two event types are the ones Stripe's fulfillment guide handles for Checkout. The second one covers delayed payment methods.

Next.js Pages Router

The API routes docs list webhook signature checks as the reason to turn off the body parser:

// pages/api/webhooks/stripe.js
export const config = { api: { bodyParser: false } };

async function rawBody(req) {
  const chunks = [];
  for await (const chunk of req) chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
  return Buffer.concat(chunks);
}

export default async function handler(req, res) {
  const buf = await rawBody(req);
  try {
    const event = stripe.webhooks.constructEvent(buf, req.headers['stripe-signature'], process.env.STRIPE_WEBHOOK_SECRET);
    // ...handle event
    res.status(200).end();
  } catch {
    res.status(400).send('Invalid signature');
  }
}

Express

Give the webhook route express.raw() and register it before any global express.json():

app.post('/api/webhooks/stripe', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = stripe.webhooks.constructEvent(req.body, req.headers['stripe-signature'], process.env.STRIPE_WEBHOOK_SECRET);
  } catch {
    return res.status(400).send('Invalid signature');
  }
  // ...handle event
  res.sendStatus(200);
});

app.use(express.json()); // everything else

Supabase Edge Functions (Deno)

Deno needs the async verifier and a Web Crypto provider, as in Supabase's Stripe example:

import Stripe from 'npm:stripe';

const stripe = new Stripe(Deno.env.get('STRIPE_API_KEY')!);
const cryptoProvider = Stripe.createSubtleCryptoProvider();

Deno.serve(async (req) => {
  const signature = req.headers.get('Stripe-Signature') ?? '';
  const body = await req.text(); // raw body

  let event;
  try {
    event = await stripe.webhooks.constructEventAsync(
      body, signature, Deno.env.get('STRIPE_WEBHOOK_SIGNING_SECRET')!, undefined, cryptoProvider,
    );
  } catch (err) {
    return new Response((err as Error).message, { status: 400 });
  }

  // ...handle event
  return new Response(JSON.stringify({ received: true }), { status: 200 });
});

The synchronous constructEvent doesn't work there, and neither does parsing JSON first.

One more thing: don't rely on the success page

Even with a perfect webhook, fulfilling only on the redirect page will eventually miss someone. Stripe says: "You can't rely on triggering fulfillment only from your checkout landing page, because it's not guaranteed customers visit that page" (Stripe fulfillment docs). Call the same idempotent fulfill() from both the webhook and the success page.

And once it's fixed, you don't have to wait for retries. In live mode Stripe retries failed deliveries for up to three days (Stripe webhooks docs), and you can resend a failed event from the Dashboard right away. For the customers who already paid, run fulfill() for their Checkout Session IDs.

Quick checklist

[ ] The URL in Stripe is the final URL: no 3xx from curl -i -X POST
[ ] No JWT, login, deployment protection or auth middleware in front of the route
[ ] An unsigned POST gets a 400, not a 200
[ ] Verification uses the raw body and the right whsec_ for the mode
[ ] Fulfillment re-checks the session via the API and is safe to run twice

If you want a second opinion on the first three, the free check at webhookproof.com runs them against your URL with 3 harmless requests and shows the results. WebhookProof is an independent tool, not affiliated with Stripe, Inc.

DEV Community: WebhookProof

Stripe webhook timestamp outside the tolerance zone? Fix the clock, don't set tolerance to 0

What the timestamp is for

The default tolerance

Fix the clock

Retries are not the cause

Why a tolerance of 0 is a trap

Checklist

Sources

Stripe webhook timed out? Return a 2xx first, then do the heavy work in a queue

How to tell if the endpoint is timing out

What Stripe asks the handler to do

Why a slow response is worse than it looks

Hand the work to a queue

Fix the failures that already happened

Things that keep the timeout coming back

Checklist

Sources

Refunded or disputed, but the customer still has access? Your Stripe webhook only listens for the purchase

How to tell if access is one-way

The events that should take access away

Map the event back to the user

Decide the edge cases before they happen

Things that make revocation fail quietly

Clean up the customers who already kept access

Checklist

Sources

Customers paid while your Stripe webhook was down? How to find and recover every missed order

First, how much time Stripe gives you

Step 1: Confirm the live endpoint is enabled

Step 2: List exactly what failed

Step 3: Replay them without doing anything twice

Step 4: Make the endpoint answer the retries

Only a few events? Resend them instead

Older than 30 days?

Next time, find out the same day

Checklist

Sources

Can someone fake a Stripe payment to your app? Only if your webhook skips the signature check

Stripe spells out the risk

Why a hidden URL doesn't help

What Stripe says protects you

What about replaying a real event?

A second check that a forged event can't pass

Test your own endpoint in one command

Checklist

Sources

Stripe sent the same webhook twice. Make fulfillment idempotent before it costs you

Why the same payment arrives more than once

What to key on

The pattern: claim first, then fulfill

Don't confuse this with Idempotency-Key

Keep the handler fast

Checklist

Sources

Stripe webhooks broke the day you went live? Check which whsec_ you're using

One endpoint, one mode, one secret

Why the error looks like this

The three secrets that get mixed up

How to tell which one you have

Swapping the secret without losing events

Don't fix it by turning verification off

Go-live checklist

Sources

Customer paid in your Lovable or Bolt app but nothing unlocked? Where to look first

Step 0: find out which setup you have

Lovable with your own Stripe account: no webhooks by default

1. One-time purchases granted only on the success page

2. Subscriptions matched by email

Bolt: the webhook function exists, so check that it runs

Reading the status code (both builders)

Test vs live: the go-live trap

Fixing customers who already paid

Checklist

Sources

Stripe webhook shows 307 or 308 on Vercel / Next.js? It's a redirect, and Stripe won't follow it

Why a redirect counts as a failure

Why 307 and 308 specifically

Cause 1: the trailing slash

Cause 2: apex vs www (domain redirect)

Don't confuse this with `Idempotency-Key`

Cause 3: a `redirects()` rule that matches the webhook path

In `config.toml` (sticks across deploys)