← 返回博客
Billing发布于 2026-03-21· 12 分钟阅读

Next.js 订阅计费:真正可用的 Webhook 契约

WangNan, author at Uncorne
作者 WangNan
出品方 Uncorne · 更新于 2026-10-09

多数订阅计费教程止步于顺利路径:创建结账会话、跳转浏览器、收工。这在演示里能跑,但客户在付款中途关掉标签页、支付商重试事件、或者测试触发两次时就会崩。生产级计费恰恰活在那些被跳过的地方。本文是 Uncorne 生成应用背后的契约——五家支付商共用一套验证与权限层——以及每一条规则背后的理由。

Next.js 订阅计费 Webhook 流程
Next.js 订阅计费 Webhook 流程

浏览器不是真相来源

一次成功的跳转只是提示,不是事实。客户可能付完款、但在你的成功页加载前就关了标签页。Webhook 可能比跳转先到、到两次,或者因为验签失败而根本没到。把跳转当成 cosmetic 的致谢页就好,别当成凭据。

你的数据库才是唯一真相来源,而且只有一样东西能往里写订阅状态:支付商发来的、已验签的 Webhook。其它一切——成功页、轮询支付商 API、客服的备注——都只能读这个库。搞反了,你迟早会把访问权限给没付钱的人,或者把付了钱的人挡在门外。Stripe 官方的订阅概览列出了值得处理的生命周期事件;实用法则是:少处理几种事件、把每种都处理对、其余的显式忽略而不是静默吞掉。

把验签契约写清楚

验签必须是路由做的第一件事——在解析 body 之前、在碰数据库之前、在记录任何含客户数据的日志之前。这份契约值得写下来,因为写反了是安全漏洞,不是风格偏好:

  • 签名缺失、无效或格式损坏 → 抛错。路由返回 400,不写任何东西。
  • 合法已验签、但无需处理的事件 → 返回空结果,并以 200 标记 ignored。
  • 已见过的事件 id → 在任何写入之前跳过。
  • 合法、未见、需处理的事件 → 写入,并在同一事务里记录事件 id。

早期版本的 Uncorne 适配器在验签失败时返回空列表,等于用 200 确认了伪造请求。我们改成验签失败直接抛错,路由根本来不及确认任何东西。别退回那种取舍——200 是一个承诺,只有按 Stripe Webhook 签名指南验过签之后才能给。

export async function POST(req: Request) {
  const raw = await req.text();               // 用原始 body 验签
  let event: ProviderEvent;
  try {
    event = verifyAndParse(raw, req.headers); // 签名错误时抛异常
  } catch {
    return new Response("invalid signature", { status: 400 });
  }
  if (shouldIgnore(event)) {
    return json({ ignored: true, handled: [] });
  }
  const fresh = await markSeen(event.id);     // 原子插入,重复则返回 false
  if (!fresh) return json({ ignored: true, duplicate: true });
  await applyPlanChange(event);               // 写 customer -> plan
  return json({ handled: [event.type] });
}

要用原始请求体验签,绝不要用重新序列化过的对象。JSON 键顺序和空白在不同支付商、不同 SDK 版本之间并不稳定,重新序列化是让一个本来正确的签名失效的经典方式。用 req.text() 读一次 body,把这串字节原样交给验签器,之后才解析成对象。

Webhook 签名验证时序
Webhook 签名验证时序

幂等不是可选项

支付商会重试。如果接口慢、返回 500、或者超时,那条发放套餐的 Webhook 会被再送一次。没有去重步骤,第二次投递可能重置用户配额、把订阅延长两次、或者再发一封欢迎邮件。建一张表记录你处理过的每个事件 id:

create table webhook_events (
  provider   text not null,
  event_id   text not null,
  type       text not null,
  received_at timestamptz not null default now(),
  primary key (provider, event_id)
);

插入就是闸门:用冲突时返回 false 的原子插入,只在返回 true 时继续。在 Supabase 里是带 onConflict 的 upsert 加冲突分支;本地 SQLite 路径是 INSERT ... ON CONFLICT DO NOTHING 再检查变更行数。数据库支持的话,把去重和套餐写入放进同一个事务,这样崩溃不会留下「事件已记录、套餐没改」的状态。保留这些行的时长至少覆盖支付商的重试窗口——Stripe 最多重试三天,保留 30 天是很宽裕的余量。

权限在服务端,绝不在界面

隐藏按钮不等于访问控制。每个受保护路由都要从会话或数据库读套餐,并在那里做决定。在 App Router 里,这意味着用 cookies() 读会话 cookie 并查询权限的路由处理器或 server action——不是一个检查 prop 的客户端组件。套餐未激活时,AI 接口返回 402,哪怕有人在 devtools 里改了 DOM,或者直接用 curl 调 API。

export async function POST(req: Request) {
  const session = await getSession();
  if (!session?.user) return new Response("unauthorized", { status: 401 });
  const entitlement = await getEntitlement(session.user.id);
  if (!entitlement.active) {
    return Response.json({ code: "no_entitlement" }, { status: 402 });
  }
  return streamAnswer(req, session.user.id);
}

Server Actions 与变更同理:在 action 内部授权,而不是在渲染表单的组件里。客户端检查是为了体验,服务端检查是为了安全。如果只能做一种,做服务端那种。一个有用的习惯是先写服务端检查,再把 UI 当作一个已做决定的映射。

服务端套餐权限流程
服务端套餐权限流程

402 和 429 是两种答案

两种失败状态经常被混为一谈。402 表示没有权限——没有有效授权码、没有生效订阅、没有验证过的邮箱认领。429 表示客户有权限,但用光了配额。混用会让面板误导人、让客服头疼,因为前者的解法是「买套餐」,后者的解法是「等重置」。

| 状态 | 错误码 | 含义 | 客户端应该做什么 | | --- | --- | --- | --- | | 402 | no_entitlement | 无有效授权码或订阅 | 打开账单门户 | | 402 | preview_limit_reached | 匿名预览配额用尽 | 引导注册 | | 429 | quota_exceeded | AI 每日配额用尽 | 显示重置时间 | | 400 | invalid_signature | Webhook 验签失败 | 什么都不做——纯服务端 |

订阅状态和使用限额不是一回事。AI 接口另有每用户每日配额(AI_MESSAGES_PER_DAY,默认 50),由 Supabase RPC 或本地 SQLite 的 ai_usage 表扣减。用尽时返回 429,带 X-AI-Quota-Reset 头,以及按真实重置时间戳算出的、以秒为单位的 Retry-After——不是写死的 86400。假的重试提示比没有还糟:它会训练客户端忽略这个头,也让客服只能靠猜。

一份结账契约,五家支付商

Uncorne 在同一个接口后面提供 Waffo、Stripe、Creem、PayPal 和 Lemon Squeezy 的适配器。每个适配器把支付商的事件映射成一小套内部词汇——activated、renewed、cancelled、past due——权限层只理解这套词汇。于是切换支付商只是改配置加更新 Webhook URL,而不是重写产品代码。Stripe Checkout Sessions API 很适合作为你需要归一化的字段参考:customer id、subscription id、price id 和当前周期结束时间。

取舍也诚实说明:通用契约就是最小公分母。按量计费、Merchant of Record 的税务处理这类支付商特有功能,需要一个逃生舱。给适配器保留一个承载支付商专有数据的方法,并写明它故意不可移植,免得有人以为这层抽象是魔法。

一份结账契约背后的五家支付适配器
一份结账契约背后的五家支付适配器

退款、取消,以及「生效」到底是什么意思

一个订阅在一个系统里可能生效,在另一个系统里却被退款。除了订阅事件,也要监听退款和拒付事件,并把全额退款当成立即撤销,而不是等到周期结束。取消时优先用 cancel_at_period_end,让客户在已付费周期内保留访问,也省掉一条「第一天就丢了数据」的客服工单。

把支付商的原始状态和你归一化后的权限并存保存,永远不要从「注册时设过一次的布尔值」推断「生效」。改成读取时根据你应用过的最新事件重算。这一处改动就能修掉一类让人意外的 bug:套餐在数据库里看着对,在产品里却是错的。

离线测试安全不变量

验证这份契约不需要五个沙箱账户。Uncorne 提供离线签名探测——npm run probe:webhook——向运行中的服务发送四种 body:合法签名、签名缺失、签名损坏、JSON 格式错误。它断言上表里的状态码,所以任何「验签失败也回 200」的回归都会在 CI 里挂掉。Stripe Webhook 指南记录了真实沙箱会投递的事件类型;用那份清单来搭建你的端到端用例。

四层测试,按真实度递增:

  1. 固定 fixture 下对验签函数做单元测试。
  2. 对运行中的开发服务器跑离线探测——不需要任何凭据。
  3. 用各家测试密钥跑沙箱端到端,包括一次真实重试。
  4. 部署后跑一次小额金丝雀:一笔低金额订阅,随即退款。

第 1、2 层属于 CI,应该很快。第 3、4 层是上线闸门。跳过离线层是常见错误:它是唯一一个不依赖外部服务就能抓住「失败也回 200」bug 的层。

离线 Webhook 探测输出
离线 Webhook 探测输出

值得提前设计的失败场景

有些情况罕见到容易被忘,又常见到真会疼。续费 Webhook 迟到了,你的定时任务已经先撤销了访问——别孤立地应用事件,而是根据支付商当前状态重算权限。客户升级,两个订阅事件乱序到达——存下周期结束时间戳,忽略比已应用事件更旧的事件。Webhook 签名正确,但引用的 customer id 你还不存在——排队等用户创建后重试,别直接丢掉。

可观测性在这里很重要。用哈希后的客户 id 记录事件 id、类型和做出的决定(handled、ignored、duplicate、failed)。别记原始 body;它含个人数据,可能还有支付方式 token。当客户说「我付了钱但还是进不去」,你应该能用一条查询回答:到了哪些事件、你对每个事件做了什么。

上线前简短清单

  • 原始 body 验签失败必抛错,永不返回 200。
  • 每个已处理事件 id 在写套餐前原子记录。
  • 受保护路由在服务端读权限,没有只在客户端的门禁。
  • 402 与 429 带稳定的机器可读错误码和诚实的重试头。
  • 离线探测在每个 PR 的 CI 里运行。
  • 上线前每家支付商至少跑一次沙箱端到端。

创建产品和结账路由的完整流程,见如何给 Next.js 添加 Stripe 订阅。计费在模板中的位置,见自带 Stripe 与登录的 Next.js SaaS 模板该检查什么。

订阅计费难,不是因为 API 难,而是因为边界情况在真实客户撞上之前一直隐身。把契约写下来,在离线环境测不变量,让 Webhook——而不是浏览器——决定谁能访问。

FAQ

浏览器跳转足以发放付费权限吗?+

不够。跳转只是提示,不是付款凭据。只有已验签的 Webhook 才能把订阅状态写入数据库;其它一切(包括成功页)都只能读这个库。这能防止没付款就关标签页、或重放回调的人拿到权限。

Webhook 怎么做幂等?+

把支付商事件 id 存进 webhook_events 表,并以 (provider, event_id) 为主键,在写套餐或 license 前做原子插入。验签在最前面,只有合法且未处理的事件才进入去重步骤。Stripe 最多重试三天,行至少保留 30 天。

订阅应用里 402 和 429 有什么区别?+

402 表示没有权限——没有有效授权码、生效订阅或验证过的邮箱认领。429 表示客户有权限但 AI 每日配额用尽。预览额度耗尽是另一个 402,错误码 preview_limit_reached。402 靠买套餐解决,429 靠等重置解决。

在 Next.js 里该怎么验 Webhook 签名?+

用 req.text() 读一次原始请求体,把这串字节原样交给验签器,之后才解析成对象。签名缺失、无效或格式损坏要抛错,让路由返回 400 且不写任何东西。先重新序列化 JSON 可能让正确的签名失效,因为键顺序和空白会变。

没有沙箱账户能测订阅计费吗?+

共用验签契约可以用 npm run probe:webhook 离线验证:它向运行中的服务发送合法、签名缺失、签名损坏、JSON 格式错误四种请求并断言状态码。但每家通道的真实结账流程上线前仍需各自的沙箱凭据;四层策略见 docs/payment-testing.md。

全部常见问题 · Markdown 版本(供 AI 智能体阅读)