> ## 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 シークレットに対して暗号署名を検証し、データベースクエリを 1 つでも実行する前に失敗したリクエストを HTTP 400 で拒否してください。[課金モジュールガイド](https://supastack.dev/ja/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 });
}
```


## メモリ内ではなくデータベース境界で重複排除する

Stripe や Lemon Squeezy は、デプロイの再起動、サーバーレス関数のタイムアウト、ネットワーク経路での応答ロストが発生するたびに Webhook を再送します。プロセスローカルな Set や短命なキャッシュキーはインスタンス間で消えてしまうため、2 つの同時リトライが重複したライセンスを発行したり、領収書メールを 2 通送信したりするのを防げません。

サブスクリプションのアクセス権を更新するのと同じ Postgres トランザクション内で、プロバイダーのイベント ID または注文の決済ステータスを記録します。アトミックな `INSERT ... ON CONFLICT DO NOTHING` や `status != 'paid'` を条件とした更新により、並行する再送は安全な no-op になります。Webhook が処理するプランを設計する際は、[SaaS 料金ページジェネレーター](https://supastack.dev/ja/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 はユーザーがクリックした順序どおりに届くとは限りません。`checkout.session.completed` より先に `customer.subscription.updated` が届くこともありますし、誤って 2 つの決済タブを開いた顧客が同じワークスペース内で一時的に 2 つのサブスクリプションを持つこともあります。

解約や決済失敗は、そのイベントを発生させた特定のサブスクリプション ID に紐付けて処理してください。ワークスペースの有料エンタイトルメントを取り消す前に、同じワークスペースをカバーする別の有効なサブスクリプションが残っていないかを確認します。そうしないと、重複分を解約しただけで顧客が支払い続けているアクセス権まで静かに失われてしまいます。

- サブスクリプションの状態は `workspaceId` だけでなく `providerSubscriptionId` をキーにして管理する。
- 少なくとも 1 つのサブスクリプションが `active` または `trialing` である限り、ワークスペースの有料エンタイトルメントを維持する。
- 買い切り注文を履行する前に、支払額と通貨が期待される SKU と一致していることを検証する。


## SaaS 課金 Webhook に関するよくある質問

サンドボックスでの決済テストから本番トラフィックへ移行する際、どのチームでも次の疑問が浮かびます。

- 決済完了リダイレクトの時点で有料機能を解放してもよいですか？, いいえ。リダイレクト URL はブックマークや共有が可能であり、非同期決済が完了する前に開かれることもあります。検証済み Webhook がアクセス権を付与する間、完了ページはサーバーの状態をポーリングするために使ってください。
- 重複した Webhook にはどのステータスコードを返すべきですか？, イベントが処理済みであることをデータベースで確認できたら、`200 OK` を返します。`4xx` や `5xx` を返すと、プロバイダーは再送を続けてしまいます。
- ローカルで Webhook の再送をテストするにはどうすればよいですか？, 全く同じ署名付きペイロードを 2 回送信する決定論的なユニットテストを書き、ライセンス、エンタイトルメント、トランザクションメールが 1 つだけ生成されることを検証します。
- モバイルのアプリ内課金は同じモデルにどう統合しますか？, RevenueCat のサーバー通知を同じべき等なエンタイトルメントテーブルにルーティングし、Web とモバイルの購入が互いを上書きしないようにします。リリース前の確認項目は[ローンチチェックリスト](https://supastack.dev/ja/blog/saas-launch-checklist.md)を参照してください。
