Webhook エンドポイントで Stripe イベントを受信する

Stripe のシステムを構築する際、自社のアプリが Stripe アカウントで発生するイベントを受信できるようにすることをお勧めします。こうすることで、バックエンドシステムは適宜アクションを実行できます。

HTTPS Webhook エンドポイントでイベントを受信するためのイベントの送信先を作成します。Webhook エンドポイントを登録すると、Stripe は、Stripe アカウントで Event (イベント) が発生した際に、リアルタイムのイベントデータをアプリの Webhook エンドポイントにプッシュできます。Stripe は、HTTPS を使用して、Event オブジェクトを含む JSON ペイロードとして Webhook イベントをアプリに送信します。

Webhook イベントの受信は、顧客の銀行が支払いを確定したとき、顧客が支払いに対して不審請求を申請したとき、継続支払いが成功したとき、サブスクリプションの支払いを回収するときなど、非同期イベントをリッスンする際に特に便利です。

イベントの送信先を指定して Amazon EventBridge でイベントを受信することもできます。

始める

アプリで Webhook イベントの受信を開始するには、以下のようにします。

1. Webhook エンドポイントハンドラを作成して、イベントデータの POST リクエストを受信します。
2. Stripe CLI を使用して、ローカルで Webhook エンドポイントハンドラをテストします。
3. Webhook エンドポイントに新しいイベントの送信先を作成します。
4. Webhook エンドポイントを保護します。

1 つのエンドポイントを登録、作成して、複数のイベントタイプを同時に処理するか、特定のイベントに個別のエンドポイントを設定することができます。

require 'json'

# Using Sinatra
post '/webhook' do
  payload = request.body.read
  event = nil

  begin
    event = Stripe::Event.construct_from(
      JSON.parse(payload, symbolize_names: true)
    )
  rescue JSON::ParserError => e
    # Invalid payload
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'payment_intent.succeeded'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    # Then define and call a method to handle the successful payment intent.
    # handle_payment_intent_succeeded(payment_intent)
  when 'payment_method.attached'
    payment_method = event.data.object # contains a Stripe::PaymentMethod
    # Then define and call a method to handle the successful attachment of a PaymentMethod.
    # handle_payment_method_attached(payment_method)
  # ... handle other event types
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end

stripe listen --forward-to localhost:4242/webhook

stripe listen --events payment_intent.created,customer.created,payment_intent.succeeded,checkout.session.completed,payment_intent.payment_failed \
  --forward-to localhost:4242/webhook

stripe listen --load-from-webhooks-api --forward-to localhost:4242/webhook

Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)

stripe trigger payment_intent.succeeded
Running fixture for: payment_intent
Trigger succeeded! Check dashboard for event details.

エンドポイントを登録する

Webhook エンドポイント関数をテストしたら、Workbench の API または Webhook タブで Webhook エンドポイントがアクセス可能な URL を登録し、イベントの送信先を Stripe が認識していることを確認します。Stripe では最大 16 個の Webhook エンドポイントを登録できます。登録される Webhook エンドポイントは、パブリックアクセス可能な HTTPS URL である必要があります。

Webhook の URL 形式

Webhook エンドポイントを登録するための URL 形式は、次のとおりです。

https://<your-website>/<your-webhook-endpoint>

たとえば、ドメインが https://mycompanysite.com で、Webhook エンドポイントへのルートが @app.route('/stripe_webhooks', methods=['POST']) の場合、エンドポイント URL には https://mycompanysite.com/stripe_webhooks を指定します。

Webhook エンドポイントのイベント送信先を作成する

ダッシュボードのワークベンチを使用するか、API を使用してプログラムでイベントの送信先を作成します。Stripe アカウントごとに最大 16 のイベントの送信先を登録できます。

ダッシュボード

API

ダッシュボードで新しい Webhook エンドポイントを作成するには、以下のようにします。

1. Workbench で Webhook タブを開きます。
2. イベントの送信先を作成するをクリックします。
3. イベントの送信元を選択します。Stripe は、お客様のアカウントと連結アカウントの 2 つのタイプの設定をサポートしています。自分のアカウントからのイベントをリッスンするには、アカウントを選択します。Connect アプリケーションを作成して、連結アカウントからのイベントをリッスンする場合は、連結アカウントを選択します。
4. 使用する Event オブジェクトの API バージョンを選択します。
5. Webhook エンドポイントに送信するイベントタイプを選択します。
6. 続行を選択して、送信先のタイプとして Webhook エンドポイントを選択します。
7. 続行をクリックして、Webhook のエンドポイント URL とオプションの説明を指定します。

Webhook タブで新しい Webhook を登録する

注

既存の開発者ダッシュボードはワークベンチに置き換えられます。開発者ダッシュボードを引き続き使用している場合は、新しい Webhook エンドポイントを作成する方法をご覧ください。

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

require 'stripe'
require 'sinatra'

# If you are testing your webhook locally with the Stripe CLI you
# can find the endpoint's secret by running `stripe listen`
# Otherwise, find your endpoint's secret in your webhook settings in
# the Developer Dashboard
endpoint_secret = 'whsec_...'

# Using the Sinatra framework
set :port, 4242

post '/my/webhook/url' do
  payload = request.body.read
  sig_header = request.env['HTTP_STRIPE_SIGNATURE']
  event = nil

  begin
    event = Stripe::Webhook.construct_event(
      payload, sig_header, endpoint_secret
    )
  rescue JSON::ParserError => e
    # Invalid payload
    puts "Error parsing payload: #{e.message}"
    status 400
    return
  rescue Stripe::SignatureVerificationError => e
    # Invalid signature
    puts "Error verifying webhook signature: #{e.message}"
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'payment_intent.succeeded'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    puts 'PaymentIntent was successful!'
  when 'payment_method.attached'
    payment_method = event.data.object # contains a Stripe::PaymentMethod
    puts 'PaymentMethod was attached to a Customer!'
  # ... handle other event types
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end

Webhook との連携のデバッグを行う

Webhook エンドポイントにイベントを送信する際に、以下のような複数のタイプの問題が発生することがあります。

• Stripe が Webhook エンドポイントにイベントを送信できない可能性がある
• Webhook エンドポイントで SSL の問題が発生している可能性がある
• ネットワーク接続が断続的である
• Webhook エンドポイントが、受信する予定のイベントを受信していない

イベントの送信を表示する

イベント配信を表示するには、Webhook で Webhook エンドポイントを選択し、イベントタブを選択します。

イベントタブには、イベントのリストと、各イベントが Delivered、Pending、Failed のいずれであるかが表示されます。イベントをクリックして、Delivery attempts を表示すると、以前行われた配信の試行の HTTP ステータスコードや、保留中になっているイベントの今後の配信時刻が示されます。

Webhook エンドポイントのイベントタブで、イベント送信の試行を表示します。

HTTP ステータスコードを修正する

イベントにステータスコード 200 が表示されている場合は、Webhook エンドポイントへの送信が成功したことを示しています。200 以外のステータスコードを受信する場合もあります。次の表で、一般的な HTTP ステータスコードと推奨される解決方法の一覧をご覧ください。

イベント送信の動作

このセクションは、Stripe が Webhook エンドポイントにイベントを送信する際に想定されるさまざまな動作を理解するのに役立ちます。

自動での再試行

本番環境では、Stripe は指数バックオフを使用して最長 3 日間、送信先へのイベントの配信を試行します。イベント送信先のイベントの配信タブで、該当がある場合、次回の再試行のタイミングを確認します。Stripe はサンドボックスで作成されたイベントの配信を数時間のうちに 3 回再試行します。Stripe が再試行するときに、送信先が無効化または削除されていた場合、そのイベントの以降の再試行は行われません。ただし、Stripe が再試行できるようになる前にイベントの送信先を無効にして、再び有効にした場合は、以降の再試行が引き続き行われます。

手動での再試行

There are two ways to manually retry events:

• In the Stripe Dashboard, click Resend when looking at a specific event. This works for up to 15 days after the event creation.
• With the Stripe CLI, run the stripe events resend <event_id> --webhook-endpoint=<endpoint_id> command. This works for up to 30 days after the event creation.

イベントの順序付け

Stripe は、イベントが生成された順序で配信されることを保証しません。たとえば、サブスクリプションを作成することで、次のイベントが生成されるとします。

• customer.subscription.created
• invoice.created
• invoice.paid
• charge.created (支払いが付随する場合)

イベントの送信先が、特定の順序でのイベントの受信に左右されないようにしてください。配送を適切に管理できるように準備します。API を使用して不足しているオブジェクトを取得することもできます。たとえば、最初に受信したイベントが invoice.paid であった場合は、それに含まれる情報を使用して請求書、支払い、サブスクリプションの各オブジェクトを取得できます。

API のバージョン管理

イベント発生時のアカウント設定内の API バージョンによって、API バージョンが指定され、それにより送信先に送られる Event (イベント) の構造が決定されます。たとえば、アカウントが 2015-02-16 のように以前の API バージョンに設定されている場合、特定のリクエストに対して versioning (バージョン管理) で API バージョンを変更しても、生成され送信先に送られる Event (イベント) オブジェクトは、引き続き 2015-02-16 API バージョンに基づきます。Event オブジェクトは、作成されると変更できません。たとえば、請求を更新しても、元の請求イベントは変更されません。そのため、アカウントの API バージョンを後で更新しても、既存の Event オブジェクトがさかのぼって変更されることはありません。新しい API バージョンを使用して /v1/events を呼び出すことで以前の Event を取得しても、受信するイベントの構造には影響しません。テスト用のイベントの送信先を、デフォルトの API バージョンと最新の API バージョンのいずれかに設定できます。イベントの送信先に送られる Event は、イベントの送信先で指定されているバージョンに従って構造化されます。

Webhook 使用のベストプラクティス

これらのベストプラクティスを見直し、Webhook エンドポイントがセキュリティで保護され、システムで適切に機能することを確認してください。

重複するイベントを処理する

Webhook エンドポイントは、同じイベントを複数回受信する可能性があります。処理したイベント ID をログに記録し、すでにログに記録したイベントを処理しないようにすることで、重複するイベントの受信に対処することができます。

一部のケースでは、2 つの別々の Event オブジェクトが生成され、送信されます。これらの重複を識別するには、event.type とともに data.object のオブジェクトの ID を使用します。

構築済みのシステムに必要なイベントタイプのみをリッスンする

必要なイベントのタイプのみを受信するように、Webhook エンドポイントを設定します。その他のイベント (またはすべてのイベント) をリッスンすると、お客様のサーバーに過度の負荷がかかるため、お勧めしません。

ダッシュボードまたは API で、Webhook エンドポイントが受信するイベントを変更できます。

イベントを非同期で処理する

非同期キューで受信したイベントを処理するようにハンドラを設定します。非同期でイベントを処理することを選択した場合は、拡張性の問題が発生する可能性があります。Webhook の配信が急増すると (たとえば、すべてのサブスクリプションが更新される月初など)、エンドポイントホストが対処不可能になる場合があります。

非同期キューを使用することで、同時に発生するイベントをシステムが対応できる速度で処理できるようになります。

Webhook ルートを CSRF 保護から除外する

Rails、Django、その他のウェブフレームワークを使用している場合、貴社のサイトでは、すべての POST リクエストに 「CSRF トークン」が含まれていることを自動的に確認している可能性があります。これは、貴社とそのユーザーをクロスサイトリクエストフォージェリ の試行から保護するための重要なセキュリティ機能です。ただし、このセキュリティ対策は貴社サイトにおける正当なイベントの処理を妨げる可能性があります。この場合は、Webhook ルートを CSRF 保護から除外しなければならない可能性があります。

class StripeController < ApplicationController
  # If your controller accepts requests other than Stripe webhooks,
  # you'll probably want to use `protect_from_forgery` to add CSRF
  # protection for your application. But don't forget to exempt
  # your webhook route!
  protect_from_forgery except: :webhook

  def webhook
    # Process webhook data in `params`
  end
end

HTTPS サーバーでイベントを受信する

Webhook エンドポイント (本番環境で必要) に HTTPS URL を使用する場合、Stripe は Webhook データを送信する前に、お客様のサーバーへの接続が安全であることを確認します。これを機能させるには、お客様のサーバーが、有効なサーバー証明書で HTTPS をサポートするように正しく設定されている必要があります。Stripe の Webhook は、TLS バージョン v1.2 および v1.3 のみサポートしています。

エンドポイントの署名シークレットを定期的に取り消す

イベントが Stripe から送信されたことを確認するためのシークレットは、Workbench の Webhook タブで変更できます。シークレットを安全に保つために、定期的またはシークレットの侵害が疑われる場合にローテーション (変更) することをお勧めします。

シークレットを取り消すには、以下を行います。

1. Workbench の Webhook タブで、シークレットをローテーションするエンドポイントをクリックします。
2. オーバーフローメニュー () にアクセスし、シークレットの更新をクリックします。現在のシークレットキーをただちに有効期限切れにすることも、有効期限を最大 24 時間延長して、自社のサーバーの検証コードをご自身で更新する時間を確保することもできます。この間は、エンドポイントに対して複数のシークレットキーがアクティブになります。Stripe は、有効期限までシークレットキーごとに 1 つの署名を生成します。

イベントが Stripe から送信されたことを検証する

Stripe は、設定された IP アドレスリストから Webhook イベントを送信します。これらの IP アドレスから送信されたイベントのみを信頼してください。

この他、Webhook の署名を確認して、受信したイベントが Stripe から送信されたものであることを確かめてください。Stripe はエンドポイントに送信する Webhook イベントに署名するために、各イベントの Stripe-Signature ヘッダーに署名を含めます。これにより、お客様は、イベントがサードパーティーではなく Stripe によって送信されたことを検証できます。署名を検証するには、Stripe の公式ライブラリを使用するか、自社のソリューションを使用して手動で検証します。

次のセクションでは、Webhook の署名を検証する方法を説明します。

1. エンドポイントのシークレットを取得します。
2. 署名を検証します。

エンドポイントのシークレットを取得する

Workbench の Webhook タブに移動し、すべてのエンドポイントを表示します。シークレットを取得するエンドポイントを選択し、クリックして表示をクリックします。

Stripe は、エンドポイントごとに一意のシークレットキーを生成します。テスト API キーと本番 API キーの両方に同じエンドポイントを使用する場合、シークレットはそれぞれ異なります。さらに、複数のエンドポイントを使用する場合は、署名を検証するエンドポイントごとにシークレットを取得する必要があります。この設定後、Stripe はエンドポイントに送信する各 Webhook への署名を開始します。

リプレイ攻撃を防止する

リプレイ攻撃とは、攻撃者が有効なペイロードとその署名を傍受し、それを再送信することを言います。そのような攻撃を低減するために、Stripe は Stripe-Signature ヘッダーにタイムスタンプを含めています。このタイムスタンプは署名されたペイロードの一部であるため、署名によっても検証され、攻撃者は署名を無効にしなければタイムスタンプを変更できません。署名が有効でもタイムスタンプが古すぎる場合は、アプリケーションにペイロードを拒否させることができます。

Stripe のライブラリには、タイムスタンプと現在時刻の間に 5 分のデフォルトの許容範囲があります。この許容範囲は、署名を検証する際に追加のパラメーターを指定することで変更できます。ネットワークタイムプロトコル (NTP) を使用して、サーバーのクロックが正確であり、Stripe のサーバーの時間と同期していることを確認します。

Stripe は、イベントをエンドポイントに送信するたびにタイムスタンプと署名を生成します。Stripe がイベントを再試行する場合 (たとえば、その前にエンドポイントが 2xx 以外のステータスコードで応答した場合)、新しい配信試行に対して新しい署名とタイムスタンプを生成します。

2xx レスポンスを素早く返す

エンドポイントは、タイムアウトの原因となる複雑なロジックを実行する前に、成功を示すステータスコード (2xx) を速やかに返す必要があります。たとえば、会計システムで顧客の請求書を支払い済みとして更新する前に、200 のレスポンスを返さなければなりません。