◆ Live配信スケジュール ◆
サイオステクノロジーでは、Microsoft MVPの武井による「わかりみの深いシリーズ」など、定期的なLive配信を行っています。
⇒ 詳細スケジュールはこちらから
⇒ 見逃してしまった方はYoutubeチャンネルをご覧ください

【5/21開催】Azure OpenAI ServiceによるRAG実装ガイドを公開しました
生成AIを活用したユースケースで最も一番熱いと言われているRAGの実装ガイドを公開しました。そのガイドの紹介をおこなうイベントです!!
https://tech-lab.connpass.com/event/315703/

こんにちは、サイオステクノロジーの佐藤陽です。
今回は、Stripe の Webhook イベントの処理に関する方法を紹介します。

Webhookをトリガーとした想定外の処理が走ってしまう
Event の内容に基づき、処理を細かく制御したい

という方は是非、最後までご覧下さい！

1 はじめに
2 困りごと
- 2.1 現状の実装
- 2.2 問題発生
3 Webhook イベントを細かく制御する
- 3.1 現在のオブジェクトの値から判断
- 3.2 過去の値からの変更点から判断
  - 3.2.1 Previous Attributes
  - 3.2.2 やってみる
4 まとめ

はじめに

Stripe では Webhook の機能が提供されています。
Webhook に関する基本的な説明は、公式ドキュメントを参照してください。

なお、今回は.NET の環境で実装していきます。
少し環境依存の部分もありますが、大きな流れはどれも似た感じかなと思います。

困りごと

現状の実装

はじめに、自分が直面した困りごとについて解説します。
早く実装内容を知りたい方は、ここはスキップして次の章へお進みください！

今回、アプリの機能として、Subscription Schedule の機能を使った実装をしています。
たとえばこんな感じで Subscription の Schedule を作成します。

最初、A の SubscriptionItem で Subscription を契約
次の Phase で B の SubscriptionItem に更新
Phase 終了時に Release し、Subscription を継続

といった流れです。

この時、アプリの操作によって、以下のようにSubscriptionItemが更新されるような機能があるとします。(B->C)
処理内容は割愛しますが、UpdateSubscriptionScheduleAPI を利用すれば問題なく実装できるかと思います。

ここで本題ですが、

【 Schedule が更新されたタイミングで、何かしらのバッチ処理を走らせたい】

という要件があるとします。

StripeのWebhook には、subscription_schedule.updatedというイベントが用意されているので、これを使えば実現できそうですね。

早速 Webhook のエンドポイントを作成し、イベントを追加します。

curl https://api.stripe.com/v1/webhook_endpoints \
  -H "Authorization: Bearer ${STRIPE_SECRET_KEY}" \
  --data-urlencode "url"="https://stripe.sios.com" \
  -d "description"="Webhook Endpoint" \
  -d "enabled_events[]"="subscription_schedule.updated"

イベントキャッチ側の実装コードを抜粋すると、以下のような感じになります。

string message;   // Webhookのメッセージ
Event stripeEvent = EventUtility.ParseEvent(message);
switch (stripeEvent.Type){
    case "subscription_schedule.updated":
        /****処理を行う ****/
}

これで準備が完了です。

アプリから UpdateSubscriptionScheduleAPI を実行し、Schedule の SubscriptionItem を B から C に更新します。
すると、狙い通り Webhook のイベントが飛び、バッチ処理が走りだしました。

めでたしめでたし！！

問題発生

さーて、次は Schedule を Release するため、テストクロックを進めてみるかー！

と思ったら、ScheduleがRelease されたタイミングでも Webhook のイベントが飛び、
バッチ処理が走り出しましてしまいました。予期せぬ事態です。

StripeのDashboard から Webhook のログを見てみると、確かにイベントが飛んでいました。
ただ、Update の API を実行した記憶はない…。

ということで少し調査をすると
どうやら、Release されたタイミングでも、SubscriptionSchedule の更新イベントが飛んでいるようです。

何が Update されたかというと、Schedule の Status がactiveからreleasedに変更されたようです。
納得です。

ただ、今回の要件を満たすためには

Item が更新された時は処理を走らせる
それ以外の場合は無視する

としたいですね。
この方法を次の章から説明していきます。

Webhook イベントを細かく制御する

それでは、Webhook イベントを制御し、必要なタイミングでのみ処理を走らせる方法を紹介していきます。

わざわざ書くまでの事でもないですが

現在のオブジェクトの値から判断
過去の値からの変更点から判断

の 2 つが想定されます。

現在のオブジェクトの値から判断

こちらは特段、説明することはないかと思います。

キャッチしたイベントは、各 Stripe の Object でキャスト可能です。
今回であれば、SubscriptionSchedule に関するイベントなので、以下のようにキャストします。

すると、SubscriptionSchedule の各プロパティにアクセスできるようになります。
あとは各値を見て、処理を走らせれば OK です。

string message;   // Webhookのメッセージ
Event stripeEvent = EventUtility.ParseEvent(message);
SubscriptionSchedule subscriptionSchedule = stripeEvent.Data.Object as SubscriptionSchedule;

過去の値からの変更点から判断

こっちが今回の本題です。
現在の値だけではなく、過去の値からの変更点を見たいケースは往々にして存在します。
そんな時に役立つのが、【Previous Attributes】 というパラメータです。

Previous Attributes

Update 系の Webhook イベントには、Previous Attributes というパラメータが含まれています。
その名の通り、Update の前後での値の変化情報が含まれています。

痒い所に手が届く非常にありがたい機能ですね！

例えば、先ほどの Schedule が Release されたタイミングで飛んだイベントを確認してみます。

現在のstatus が released に変更になっている
previous attributesの status が active になっている

ことが分かるので、
今回のEvent内容から、statusが active -> released に変更になったことが伺えます。

このように、飛んできたイベント名や、現在のObject値だけで判断するのではなく
previous attributesの値も確認することで、より細かな制御が行えそうです。

やってみる

Previous Attributes を利用した実装を行ってみたいと思います。

ただ、上のケースであげた「SubscriptionItem が更新された時」に限定すると、やや階層が深く、実装が複雑になるので

ここまで色々書いておいて申し訳ないですが
今回は代わりに「Schedule の Status」の Previous Attribute をターゲットにして実装してみます。mm

あとは各々、応用で試してみたください！

なお、最初にも書きましたが今回の私の環境が.NET です。
各言語で少し実装方法が異なってくる部分かなと思いますので、参考程度に。

SDK のコードを見ると、Previous Attributes は dynamic な型として定義されていました。

/// <summary>
/// Object containing the names of the attributes that have changed, and their previous
/// values (sent along only with *.updated events).
/// </summary>
[JsonProperty("previous_attributes")]
public dynamic PreviousAttributes { get; set; }

今回は JObject の型として Cast して利用していきます。
以下のように実装することで、現在の Status と過去の Status を取得することができます。

//イベントをParse
Event stripeEvent = EventUtility.ParseEvent(message);
switch (stripeEvent.Type){
    case "subscription_schedule.updated":
        SubscriptionSchedule subscriptionSchedule = stripeEvent.Data.Object as SubscriptionSchedule;

        //現在のStatus取得
        string currentStatus = subscriptionSchedule.Status;

        //Update前のStatus取得
        string previousStatus;
        JObject previousAttributes = stripeEvent.Data.PreviousAttributes as JObject;
        if (previousAttributes.TryGetValue("status", System.StringComparison.OrdinalIgnoreCase, out JToken status))
        {
            //Previous Attributeに含まれていれば更新
            previousStatus = status.ToString();
        }else{
            //含まれていなかったら現在状態
            previousStatus= subscriptionSchedule.Status;
        }
}