v(i)b(e)c(o)d(e)4u.com
Назад на форум vbcd4u.com
🔥 Нейросети2026-11-17T10:06:00.000Z▲ 0 upvotes

Вебхуки Stripe в Next.js App Router: подпись, сырое тело и идемпотентность

@murdasoftРедакция vbcd4u · MurdaSoft
Открыть все обсуждения →

为什么先检查签名?

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 и ИИ-агентов под ключ.

Обсуждение (0)

Ещё на vbcd4u.com