> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 在 Next.js 中实现幂等的 Stripe 与 Lemon Squeezy Webhook

如何校验原始 Webhook 签名、在数据库边界对重试投递去重，并防止重叠订阅误撤消付费访问权限。

_发布于 2026-10-18._
_更新于 2026-10-18._

> **如何在 Next.js 中幂等地处理 Stripe 和 Lemon Squeezy 的 Webhook？**
> 这取决于你的计费服务商，但核心架构相同：在解析 JSON 之前先验证原始载荷签名，把各服务商的事件归一化为统一的内部契约，并在数据库边界用服务商的事件 ID 或订单 ID 强制幂等。绝不要根据客户端结账跳转授予产品权益；让验证过的 Webhook 事务性地一次性更新订阅状态与权益。supastack 已为 Stripe、Lemon Squeezy 和移动端 RevenueCat 预置了这条流水线，不过单套餐应用可以从更简单的处理器起步。

## 在解析 JSON 之前校验原始请求体

每个支付服务商都会对网络传输的原始字节序列进行签名。如果路由处理器先调用 `await request.json()` 解析再重新序列化对象去验签，键顺序或空白字符的微小差异都会导致合法的 Webhook 验签失败，甚至诱使开发者在预发环境中跳过签名校验。

在 Next.js App Router 的 `POST` 处理器中用 `await request.text()` 一次性读取原始请求体，使用仅限服务端访问的 Webhook 密钥校验加密签名，并在执行任何数据库查询之前以 HTTP 400 拒绝验签失败的请求。[计费模块指南](https://supastack.dev/zh/docs/modules/billing.md)展示了 supastack 如何将各服务商的签名校验隔离在统一的 BFF 入口之后。

- 使用 `request.text()` 读取原始请求体，切勿对已解析的 JSON 重新序列化。
- 将 `STRIPE_WEBHOOK_SECRET` 和 Lemon Squeezy 签名密钥严格保留在服务端配置中。
- 手动校验 HMAC 签名时，使用恒定时间比较（`crypto.timingSafeEqual`）。

```
export async function POST(request: Request) {
  const rawBody = await request.text();
  const signature = request.headers.get("stripe-signature");
  if (!signature) return new Response("Missing signature", { status: 400 });

  const event = stripe.webhooks.constructEvent(
    rawBody,
    signature,
    env.STRIPE_WEBHOOK_SECRET,
  );
  await handleNormalizedBillingEvent(event);
  return Response.json({ received: true });
}
```


## 在数据库边界去重，而不是在内存中去重

每当部署重启、Serverless 函数超时或网络丢包导致响应丢失时，Stripe 和 Lemon Squeezy 都会重发 Webhook。进程内存中的 Set 或短生命周期缓存键在多实例之间并不共享，无法阻止两个并发重试发放重复许可证或发送两封收据邮件。

在修改订阅访问权限的同一个 Postgres 事务内记录服务商事件 ID 或订单结算状态。原子的 `INSERT ... ON CONFLICT DO NOTHING` 或针对 `status != 'paid'` 的条件更新，能将并发重放安全地转化为无副作用的空操作。在设计这些 Webhook 所履约的套餐时，可以先用 [SaaS 定价页面生成器](https://supastack.dev/zh/tools/saas-pricing-generator) 规划套餐档位与席位规则。

```
const settled = await db.transaction(async (tx) => {
  const [inserted] = await tx
    .insert(billingWebhookEvents)
    .values({ providerEventId: event.id, provider: "stripe" })
    .onConflictDoNothing({ target: billingWebhookEvents.providerEventId })
    .returning({ id: billingWebhookEvents.id });

  if (!inserted) return false; // Already processed
  await applyWorkspaceEntitlement(tx, event);
  return true;
});
```

- [SaaS Pricing Page Generator (Free Tool)](https://supastack.dev/tools/saas-pricing-generator)


## 处理乱序事件与重叠订阅

Webhook 并不保证按照用户点击的顺序到达。`customer.subscription.updated` 可能先于 `checkout.session.completed` 抵达，而不小心打开两个结账标签页的客户也可能在同一个工作区中短暂拥有两份订阅。

将取消和扣款失败限定在触发该事件的特定订阅 ID 上。在撤销工作区的付费权益之前，先检查是否还有另一个活跃订阅覆盖该工作区，否则取消重复订阅会悄无声息地剥夺客户仍在付费的访问权限。

- 按 `providerSubscriptionId` 而非仅按 `workspaceId` 记录订阅状态。
- 只要工作区至少有一个订阅处于 `active` 或 `trialing` 状态，就保持其付费权益有效。
- 在履约一次性订单之前，校验实付金额与币种是否与预期 SKU 完全一致。


## SaaS 计费 Webhook 常见问题

每当团队将计费从沙盒测试切换到真实生产流量时，都会遇到以下问题。

- 可以在结账成功跳转页直接解锁付费功能吗？, 不可以。跳转 URL 可以被收藏、分享，或在异步支付方式完成结算前被访问。应当让成功页面轮询服务端状态，由经过验签的 Webhook 真正授予访问权限。
- 重复的 Webhook 应该返回什么状态码？, 一旦数据库确认该事件已处理完毕，就返回 `200 OK`。返回 `4xx` 或 `5xx` 会让支付服务商持续重试。
- 如何在本地测试 Webhook 重试？, 编写确定性的单元测试，连续两次发送完全相同的签名载荷，并断言只生成了一份许可证、一条权益记录或一封事务邮件。
- 移动端应用内购买如何融入同一模型？, 将 RevenueCat 服务端通知路由到同一张幂等权益表中，确保 Web 与移动端购买不会互相覆盖，发布前检查项请参阅[上线检查清单](https://supastack.dev/zh/blog/saas-launch-checklist.md)。
