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

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

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

Receiving webhook events helps you respond to asynchronous events such as when a customer’s bank confirms a payment, a customer disputes a charge, or a recurring payment succeeds.

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

始める

To start receiving webhook events in your app:

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.

Register your endpoint

After testing your webhook endpoint function, use the API or the Webhooks tab in Workbench to register your webhook endpoint’s accessible URL so Stripe knows where to deliver events. You can register up to 16 webhook endpoints with Stripe. Registered webhook endpoints must be publicly accessible HTTPS URLs.

Webhook の URL 形式

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

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

For example, if your domain is https://mycompanysite.com and the route to your webhook endpoint is @app.route('/stripe_webhooks', methods=['POST']), specify https://mycompanysite.com/stripe_webhooks as the Endpoint URL.

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

Create an event destination using Workbench in the Dashboard or programmatically with the API. You can register up to 16 event destinations on each Stripe account.

ダッシュボード

API

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

1. Open the Webhooks tab in Workbench.
2. Click Create an event destination.
3. Select where you want to receive events from. Stripe supports two types of configurations: Your account and Connected accounts. Select Account to listen to events from your own account. If you created a Connect application and want to listen to events from your connected accounts, select Connected accounts.

1. Select the API version for the events object you want to consume.
2. Select the event types that you want to send to a webhook endpoint.
3. Select Continue, then select Webhook endpoint as the destination type.
4. Click Continue, then provide the Endpoint URL and an optional description for the webhook.

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

注

Workbench replaces the existing Developers Dashboard. If you’re still using the Developers Dashboard, see how to create a new webhook endpoint.

# 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

Debug webhook integrations

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 をログに記録し、すでにログに記録したイベントを処理しないようにすることで、重複するイベントの受信に対処することができます。

In some cases, two separate Event objects are generated and sent. To identify these duplicates, use the ID of the object in data.object along with the event.type.

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

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

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

Handle events asynchronously

非同期キューで受信したイベントを処理するようにハンドラを設定します。非同期でイベントを処理することを選択した場合は、拡張性の問題が発生する可能性があります。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 アドレスから送信されたイベントのみを信頼してください。

Also verify webhook signatures to confirm that Stripe sent the received events. Stripe signs webhook events it sends to your endpoints by including a signature in each event’s Stripe-Signature header. This allows you to verify that the events were sent by Stripe, not by a third party. You can verify signatures either using our official libraries, or verify manually using your own solution.

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

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

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

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

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

リプレイ攻撃を防止する

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

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

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

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

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