Webhook の直接応答への移行

Issuing のリアルタイムのオーソリを API コールから Webhook の直接応答に移行する方法について説明します。

Webhook の実行中に承認エンドポイントと拒否エンドポイントへの API コールを行う代わりに、リアルタイムのオーソリの決定で issuing_authorization.request Webhook に直接応答することができるようになりました。

Webhook イベントに直接応答することで、リアルタイムのオーソリが効率化されます。また、タイムアウトによってオーソリ率が低下する可能性のある余分な API コールを排除できます。

新しいシステムを構築している場合は、承認または拒否の API コールを行う代わりに、新しい Webhook の直接応答を使用します。承認と拒否のエンドポイントは非推奨となりましたが、既存のユーザーは少なくとも 2024 年の年末までは引き続きアクセスすることができます。リアルタイムオーソリの既存の実装がある場合は、Webhook の直接応答への移行をご計画ください。

注

このガイドは、リアルタイムのオーソリに /approve エンドポイントおよび /decline エンドポイントを使用する場合にのみ適用されます。

レガシー API コールフロー

これまでは、issuing_authorization.request Webhook に応答する前に、着信オーソリリクエストに対して /approve API コールまたは /decline API コールを行って決定する必要がありました。

新しい Webhook 直接応答フロー

個別の API コールを行わなくても、レスポンス本文に決定情報を指定して issuing_authorization.request Webhook に直接応答できるようになりました。決定の後も issuing_authorization.created Webhook イベントまたは issuing_authorization.updated Webhook イベントが送信されます。

この API について、詳細はリアルタイムのオーソリに関するドキュメントをご覧いただき、対話型ガイドを参照してシステムを構築してください。

HTTP ステータスコード 200、特定の API バージョンに設定された Stripe-Version ヘッダー、および JSON 本文のブール値 approved で応答する必要があります。JSON 本文は指定の API バージョンに対応している必要があります。

管理可能な金額のオーソリでは、部分的な承認にオプションで amount を含めることができます。

Webhook 直接応答 Authorization API の変更

Webhook の直接応答 Authorization (オーソリ) について、以下が追加されています。

request_history.reason に値 webhook_error が追加されました。この値は、Webhook レスポンスが検証エラーで失敗した場合に表示されます。
新しいフィールド request_history.reason_message が追加されました。このフィールドには、request_history.reason が webhook_error の場合に詳細なエラーメッセージが入ります。

直接応答への移行

テスト環境で Webhook の直接応答を試すことができます。ベストプラクティスとして、レガシー API コールから Webhook への直接応答に段階的に移行することをお勧めします。

API メソッドを呼び出し、Webhook の直接応答の本文を含めた場合、API メソッドの決定が優先されます。

以下のコードは、Ruby の場合に Webhook の直接応答への移行がどのようになるかを示す例です。他の言語については、対話型ガイドを参照してください。

# User's existing API call webhook handling code, using Sinatra.
# In this example, the synchronous webhook and normal webhook share an endpoint.
post '/webhook' do
  payload = request.body.read

  if event['type'] == 'issuing_authorization.request'
    auth = event['data']['object']
    # Approve with legacy API call.
    Stripe::Issuing::Authorization.approve(auth["id"])
    status 200
  elsif event['type'] == 'issuing_authorization.created'
    auth = event['data']['object']
    # If approved, will print "webhook_approved"
    puts "#{auth["request_history"][-1]["reason"]}"
    status 200
  end
end

テスト環境でテストした後、トラフィックを段階的に Webhook の直接応答に移行します。

# User's API call and direct response webhook handling code, using Sinatra.
# In this example, the synchronous webhook and normal webhook share an endpoint.
post '/webhook' do
  payload = request.body.read

  if event['type'] == 'issuing_authorization.request'
    auth = event['data']['object']

    # Gradually shift traffic over from API approval to direct webhook response.
    if should_use_direct_webhook_response?(auth["id"])
      # Direct webhook response.

      body {
        # Required field, containing decision.
        "approved": true,
      }.to_json

      header {
        # Required in header. Versions can be found in https://stripe.com/docs/api/versioning
        "Stripe-Version": "2023-08-16"
      }

      # Must respond with a 200.
      status 200
    else
      # Legacy API call. Plan to remove this after traffic is completely shifted.
      Stripe::Issuing::Authorization.approve(auth["id"])
      status 200
    end
  elsif event['type'] == 'issuing_authorization.created'
    auth = event['data']['object']

    # If approved, will print "webhook_approved"
    puts "#{auth["request_history"][-1]["reason"]}"

    # Handle new reason value and field
    if auth["request_history"][-1]["reason"] == "webhook_error"
      puts "Direct webhook response decision failed: #{auth["request_history"][-1]["reason_message"]}"
    end
    status 200
  end
end