【ITニュース解説】Stripe Webhooks in Laravel: Verify, Dedupe and Retry Safely
2026年10月21日に「Dev.to」が公開したITニュース「Stripe Webhooks in Laravel: Verify, Dedupe and Retry Safely」について初心者にもわかりやすく解説しています。
ITニュース概要
Stripeでの支払い処理にはWebhookが不可欠だ。支払いの成功・失敗といった状態の真実を伝える。LaravelでWebhookを安全に扱うには、署名の検証、CSRFからの除外、素早い応答、重複の排除、順序非保証への対応、二重実行に強い処理が重要となる。エラー時も適切に処理し、常にシステムの状態を正しく保とう。
ITニュース解説
インターネット上でサービスを提供し、顧客から支払いを受け取る際、Stripeのような決済代行サービスが非常に便利だ。Stripeは、お金のやり取りそのものは安全に処理してくれるが、支払いが行われたことやその後の状態変化を、あなたのアプリケーションに確実に伝える仕組みが必要になる。ここで「Webhooks(ウェブフック)」が重要な役割を果たす。
Webhooksは、Stripe側で顧客の支払いが成功した、サブスクリプションが更新された、返金されたといった何らかのイベントが発生した際に、Stripeがあなたのアプリケーションに「こういうことが起こりましたよ」と自動的に通知を送る仕組みだ。この通知は、あなたのアプリケーションが用意した特定のURL(Webhookエンドポイント)に対して行われる。
なぜWebhooksが重要なのか。顧客が支払い完了後にWebサイトのリダイレクトページに戻ってくることを頼りに、「支払いが完了した」と判断するのは危険な行為だからだ。顧客は途中でページを閉じたり、インターネット接続が切れたり、そもそも成功ページにたどり着かない可能性がある。また、一度成功した支払いでも、後から返金や異議申し立てが発生して状態が変わることもあり得る。Webhooksは、これらの不安定な要因に左右されず、Stripeから直接、正確な支払い状態を伝える信頼できる情報源だ。あなたのアプリケーションは、このWebhookの通知を決済状態の「真の情報源」として扱い、顧客をリダイレクトする成功ページはあくまで「お礼のメッセージ」程度に考えるべきだ。
Webhooksを受け取る際、安全かつ確実な処理を行うためにはいくつかの重要なルールがある。
第一に「署名の検証」だ。あなたのアプリケーションがWebhooksを受け取るURLは一般に公開されているため、誰でもそのURLにリクエストを送ることができる。Stripeからの通知だと偽装された不正なリクエストを受け付けないように、送られてきた通知が本当にStripeから来たものなのかを確かめる必要がある。Stripeは、すべてのイベント通知に「Stripe-Signature」という特別なヘッダーを付けて送ってくる。このヘッダーには、通知の内容を基に生成された暗号化された署名が含まれており、あなたのアプリケーションは、Stripeから提供される「署名シークレット」という秘密の鍵を使って、この署名が正しいかどうかを検証する。署名が一致しない場合は、その通知を信頼せず、不正なものとして破棄すべきだ。署名検証には、リクエストの「生」のボディ(内容)が必要なので、途中の処理で内容が変更される前に読み取ることが重要だ。また、この秘密の鍵はコードの中に直接書き込まず、設定ファイルに保存し、本番環境とテスト環境で異なるものを使うべきだ。
第二に「CSRF保護からの除外」だ。Webアプリケーションには、クロスサイトリクエストフォージェリ(CSRF)という攻撃から守るための保護機能が一般的に実装されている。しかし、Stripeはブラウザではないため、CSRF保護に必要なトークンを送ることができない。そのため、Webhooksを受け取る特定のルートだけはCSRF保護の対象から外す必要がある。ただし、このルートに関しては、前述の「署名検証」がCSRF保護の代わりになるため、セキュリティが低下することはない。
第三に「高速な応答と後続処理」だ。Stripeは、Webhookの通知を送った後、あなたのアプリケーションからすぐに成功の応答(HTTPステータスコード200)が返ってくることを期待している。もし、通知を受け取ってからアプリケーションが複雑な処理(メール送信、データベースの複数のテーブル更新、他のAPI呼び出しなど)を始めると、処理に時間がかかりすぎてタイムアウトしてしまう可能性がある。タイムアウトした場合、Stripeは通知が失敗したと判断し、後で同じ通知を再送してくる。これを避けるため、Webhookエンドポイントでは、通知の署名検証、内容のデータベースへの保存、そして後で処理するためのキューへの投入といった最低限の処理だけを行い、すぐに成功応答を返すことが推奨される。実際の時間のかかる処理は、キュー(非同期処理の仕組み)を使ってバックグラウンドで実行するように設計する。
第四に「イベントIDによる重複排除」だ。ネットワークの状況やシステムの不具合などにより、Stripeは同じWebhookイベントを複数回送ってくることがある。「少なくとも一回は届く」という保証のためであり、重複は起こりうるものとして対処する必要がある。すべてのStripeイベントには「id」という一意の識別子が付けられている。このIDをデータベースに保存する際に、そのIDに対して「ユニークインデックス」を設定することで、同じIDのイベントが二度と保存されないようにできる。もし、重複したIDのイベントを保存しようとしてエラーが発生したら、それはすでに処理済みのイベントだと判断し、何もせずに成功応答を返す。
第五に「イベント順序の非依存性」だ。Webhooksは必ずしもイベントが発生した順番通りに届くとは限らない。例えば、「支払い失敗」の通知が「支払い成功」の通知より後に届く可能性もある。したがって、あなたのアプリケーションはイベントの到着順序を信頼してはいけない。常に、データベースに記録されている現在の状態を確認したり、必要であればStripeのAPIを呼び出して最新の支払い情報を取得したりして、正しい状態を判断する必要がある。
第六に「ハンドラの再実行安全性(冪等性)」だ。重複排除を行っていても、キューで処理するジョブが何らかの原因で失敗し、後で再実行される可能性がある。そのため、実際にイベントを処理する「ハンドラ」は、何回実行されてもシステムの状態が同じになるように設計すべきだ。例えば、データベースの更新を行う際には、特定のキーを使って「もし存在すれば更新、なければ作成」という処理を使ったり、メール送信やアクセス権付与の前には「すでに送ったか」「すでに付与済みか」といった状態を確認したりする。
これらのルールを踏まえた信頼性の高いシステムは、以下のような構造になることが多い。
まず「Webhookエンドポイント」の役割は、受け取ったリクエストの署名を検証し、イベントの生データとその状態(未処理など)をデータベースの専用テーブルに保存する。このとき、イベントIDにはユニーク制約を付けて重複を防ぐ。そして、実際の処理を行う「ジョブ」をキューに投入し、すぐにHTTP 200の成功応答をStripeに返す。
次に「ジョブ」は、キューからイベント情報を受け取り、データベースに保存されたイベントを読み込む。そして、そのイベントの種類に応じた具体的な処理を行う「ハンドラ」を呼び出す。処理が成功すれば、データベース上のイベントの状態を「処理済み」に更新する。もし処理中にエラーが発生しても、キューの機能を使って一定時間後に自動的に再実行(リトライ)されるように設定しておくことで、一時的な問題に対応できる。
「ハンドラ」は、それぞれのイベントタイプに特化した小さなクラスとして実装する。これにより、コードの保守性が高まり、新しいイベントタイプへの対応も容易になる。例えば、支払い成功イベント用のハンドラでは、顧客に商品へのアクセス権を付与したり、確認メールを送ったりする。
そして「デッドレタービュー」という管理機能も重要だ。これは、何度リトライしても処理が成功しなかったイベントを一覧表示し、管理者が内容を確認したり、手動で再実行したりできるような画面のことだ。これにより、システムで解決できない問題が発生した場合でも、人間の介入によってビジネスに支障が出るのを防ぐことができる。生イベントデータをデータベースに保存しておくことは、後でバグを修正した際に、そのデータを元にイベントを再実行できるという大きなメリットもある。
Stripeから送られてくるWebhookイベントは非常に多岐にわたるが、すべてのイベントを処理する必要はない。最初は、顧客の行動やビジネスに直接的な影響を与える、最も重要なイベントに絞って処理を始めるべきだ。例えば、支払いの成功や失敗、サブスクリプションの更新やキャンセル、返金やチャージバックといったイベントだ。処理すべきイベントを絞ることで、システムの複雑さを減らし、エラーの可能性も少なくなる。
Webhook処理を本番環境にデプロイする前に、徹底的なテストを行うことが不可欠だ。Stripe CLIというツールを使うと、ローカルの開発環境でStripeからのテストイベントをシミュレートしたり、特定のイベントを意図的にトリガーしたりできる。以下のようなケースを意図的にテストすることで、本番での予期せぬ問題を回避できる。正しい署名のイベント、不正な署名のイベント、内容が改ざんされたイベント、同じイベントが複数回送られてくるケース、イベントが順不同で届くケース、ハンドラの処理中にエラーが発生するケース、キューのワーカーが停止している間にイベントが届くケースだ。これらのシナリオでシステムが期待通りに動作すれば、本番環境での信頼性は大幅に向上するだろう。
もしあなたがLaravelを使っていて、標準的なサブスクリプション機能を実装しようとしているなら、「Laravel Cashier」というパッケージが非常に便利だ。Cashierは、Stripeとの連携を簡単にするために設計されており、Webhookコントローラーも内蔵されている。署名検証や一般的なサブスクリプション関連イベントの処理はCashierが自動で行ってくれるため、開発の手間を大幅に省ける。もちろん、Cashierの機能を拡張して、独自のイベント処理を追加することも可能だ。しかし、カード情報の保存と後からの課金といった、よりカスタムな決済フローを構築する場合は、自分でハンドラを実装する方が柔軟性が高い場合もある。
システムエンジニアがWebhooksを扱う際によく犯しがちな間違いもある。署名の検証を行う前に、受け取ったJSONボディをパースしてしまうことや、Webhookリクエストの処理中に、時間のかかる重い処理を実行してしまうこと、支払い完了後のリダイレクトページ到達をもって、支払いが成功したと断定してしまうこと、テスト環境と本番環境で同じ署名シークレットを使ってしまうこと、処理すべきではないイベントが届いたときに、HTTP 500エラー(サーバーエラー)を返してしまうこと(単に無視してHTTP 200を返すのが正しい)、処理に失敗したイベントを監視したり、手動で再実行したりする仕組みがないことなどが挙げられる。
これらの間違いを避けることで、Stripe Webhooksを安全かつ効率的に利用し、システムの信頼性を高めることができる。Webhooksは決済システムのバックボーンとなる重要な技術なので、その仕組みと安全な実装方法をしっかり理解することが、安定したサービス提供には不可欠だ。