Stripeから届く決済通知を使って、注文を更新したり、会員サービスを有効にしたりしている場合、通知形式の変更は業務処理にも影響します。thin eventsを検討するときは、必要な情報をどこから取得するか、移行中の二重処理をどう防ぐかを先に決めておきましょう。
本稿はStripeの公式仕様に基づく移行検討の解説です。Lumines Commerceでthin eventsの提供を開始したというお知らせではありません。
通知に含まれる情報と、取得する情報を分ける
従来のsnapshotイベントには、そのイベント時点のオブジェクト情報が含まれます。thinイベントは軽量な通知を受け取り、必要なイベントの詳細や関連オブジェクトをAPIから取得する方式です。取得したオブジェクトの最新状態と、イベント発生時点の状態は区別して扱います。イベント形式の説明
Stripeは対応するAPI v1リソースにもthinイベントを提供しています。たとえば、customer.createdに対応する名前はv1.customer.createdです。すべてのイベントを機械的に置き換える前に、自社が購読している種類が対象か確認します。API v1向けthin eventsの変更履歴
通知形式がAPIバージョンの更新に左右されにくくなっても、後から取得するリソースには通常のAPIバージョン管理が適用されます。通知を軽くすることと、業務コードのバージョン対応が不要になることは分けて考える必要があります。移行ガイド
並行受信では、同じ出来事を一度だけ反映する
移行期間にsnapshotとthinの両方を受けると、同じ出来事が異なるイベントIDで届くことがあります。IDごとに一回処理するだけでは、会員登録や通知送信などが二重に実行されるおそれがあります。
対応するthinイベントのsnapshot_eventで元のsnapshotイベントを識別できる場合は、その値を両方の経路で共通の重複判定に使います。Stripeの移行ガイドでも、この対応関係を使う手順が説明されています。並行移行と重複防止
実装では、同時に届いても一方だけが業務処理へ進むこと、途中で失敗した処理を再試行できることを確かめます。二重処理を避けるための記録だけを先に完了扱いにすると、失敗した仕事まで処理済みになるためです。ここは自社のDBやキューに合わせて設計する部分です。
まず、業務データを更新せずに結果を比べる
新しい受信先では署名を検証し、必要な情報を取得したうえで、既存処理と同じ判断になるかを記録して比べます。この段階では出荷・請求・メール送信を実行しません。情報取得が失敗した場合の再試行も確認してから切り替えます。
通知の重複や到着順の前後は、既存のWebhookでも考慮が必要です。署名検証には受信したままのリクエスト本文を使い、到着順だけで決済状態を決めないようにします。Webhookの受信と運用
最初に整理したいのは、「何のイベントで、どのデータを使い、何を変更するか」の対応表です。それがあれば、形式の変更によって確認すべき業務処理も見つけやすくなります。Stripeと既存業務システムの連携をご検討の場合は、開発相談で現在の受信処理からご相談いただけます。