Вебхуки Stripe в Next.js App Router: подпись, сырое тело и идемпотентность
为什么先检查签名?
Webhook URL 不是秘密:它可能最终出现在日志、代码、浏览器历史记录中。如果处理程序信任任何带有 JSON(如 checkout.session.completed)的 POST 请求,则任何人都可以通过自己提交订单来“支付”订单。 Stripe 使用端点特定的秘密 (whsec_...) 对每个事件进行签名,并在 Stripe-Signature 标头中传递签名。签名验证是处理程序的第一行,位于解析 JSON 和任何业务逻辑之前。
应用程序路由器中的处理程序
// app/api/stripe/webhook/route.ts
import Stripe from "stripe";
import { NextResponse } from "next/server";
import { db } from "@/lib/db";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET!;
export async function POST(req: Request) {
const signature = req.headers.get("stripe-signature");
if (!signature) return new NextResponse("missing signature", { status: 400 });
const payload = await req.text(); // сырое тело, байт в байт
let event: Stripe.Event;
try {
event = stripe.webhooks.constructEvent(payload, signature, endpointSecret);
} catch {
return new NextResponse("bad signature", { status: 400 });
}
const fresh = await db.query(
"INSERT INTO stripe_events (id, type) VALUES ($1, $2) ON CONFLICT (id) DO NOTHING",
[event.id, event.type]
);
if (fresh.rowCount === 0) return NextResponse.json({ received: true, duplicate: true });
try {
await handleEvent(event);
} catch (err) {
await db.query("DELETE FROM stripe_events WHERE id = $1", [event.id]);
throw err; // 500 — Stripe повторит доставку
}
return NextResponse.json({ received: true });
}原始身体
constructEvent 从正文中计算出与 Stripe 发送的完全相同的 HMAC。如果先调用req.json(),然后调用JSON.stringify,则键、空格和转义的顺序会不同,签名将不匹配。在 App Router 中,无需单独配置:req.text() 返回正文不变。仅旧版 Pages Router 中需要 bodyParser: false 配置。
该处理程序必须在 Node.js 运行时中运行(默认情况下)。如果您需要 Edge,请使用 Web Crypto 的异步选项:
const provider = Stripe.createSubtleCryptoProvider(); event = await stripe.webhooks.constructEventAsync(payload, signature, endpointSecret, undefined, provider);
该检查还会拒绝时间戳太旧的事件(默认容限为 5 分钟),从而防止重新提交被拦截的请求。
event.id 的幂等性
Stripe 保证“至少一次”交付。一个事件可能会发生两次:在网络故障期间、响应超时时或从仪表板手动重新发送时。在实时模式下,Stripe 会连续几天重复失败的交付。
CREATE TABLE stripe_events ( id text PRIMARY KEY, -- evt_... type text NOT NULL, received_at timestamptz NOT NULL DEFAULT now() );
带有 ON CONFLICT DO NOTHING 的插入自动回答了“我们看到这个事件了吗”的问题。如果处理失败,记录将被删除,重新投递将被重新处理。在一个事务中插入事件和订单更改更可靠:这样就不存在部分应用的状态。
##处理:不相信订单和图片
async function handleEvent(event: Stripe.Event) {
switch (event.type) {
case "checkout.session.completed": {
const session = event.data.object as Stripe.Checkout.Session;
if (session.payment_status !== "paid") return; // асинхронные методы оплаты
await markOrderPaid(session.client_reference_id!, session.id);
return;
}
case "customer.subscription.updated":
case "customer.subscription.deleted": {
const sub = event.data.object as Stripe.Subscription;
const current = await stripe.subscriptions.retrieve(sub.id);
await syncSubscription(current);
return;
}
default:
return; // неизвестные типы — 200, иначе Stripe будет повторять
}
}事件不必按发生顺序到达:subscription.updated 可能在 subscription.created 之前到达。事件中的对象是事件发生时的快照,而不是当前状态。对于订阅来说,通过API重新读取对象并同步当前状态比一一使用快照更可靠。
您在创建结帐会话时传递 client_reference_id - 使用它来查找您的订单。请与数据库中的金额进行核对,不要凭信心从活动中获取该金额。
快速回复
Stripe 等待 2xx 响应的时间有限。发送电子邮件、生成 PDF 以及在处理程序内调用第三方 API 会延长响应时间并增加重新投递的机会。将艰苦的工作放入队列或任务表中,并仅在处理程序中记录事实。
本地检查
stripe listen --forward-to localhost:3000/api/stripe/webhook # выведет whsec_... — это секрет для локального запуска, он отличается от секрета в Dashboard stripe trigger checkout.session.completed
诊断
- “未找到与预期签名匹配的签名。” 正文在验证之前已更改,或者秘密不是来自此端点。测试和实时模式、CLI 和仪表板中的每个端点都有自己的秘密。
- 签名不仅仅在生产中匹配。代理或平台在应用程序之前更改正文(压缩、重新编码)。检查请求是否在没有转换的情况下到达。
- 重复订单。
event.id或订单 ID 没有唯一约束,处理不是幂等的。 - 事件中的字段与文档不同。 事件格式由 Dashboard 中为端点选择的 API 版本决定,而不是代码中的 SDK 版本。
当更少就足够了
如果按单位付款并且手动确认订单,则检查订单的签名和唯一密钥就足够了。当付款后自动授予访问权限、发送信件或更改订阅时,事件表和队列就会自行付费。
Нужна реализация под ваш проект или аудит архитектуры?
Разрабатываем сайты на Next.js, Telegram-ботов, интеграции с CRM и ИИ-агентов под ключ.