# Webhook の直接応答への移行

Issuing のリアルタイムオーソリを、非推奨の API コールから Webhook への直接応答に移行する方法をご紹介します。

Webhook の処理中に非推奨の [approve](https://docs.stripe.com/api/issuing/authorizations/approve.md) エンドポイントと [decline](https://docs.stripe.com/api/issuing/authorizations/decline.md) エンドポイントに API コールを行う代わりに、[issuing_authorization.request webhook](https://docs.stripe.com/issuing/controls/real-time-authorizations.md) にリアルタイムのオーソリ判断を直接返すことができます。Webhook イベントに直接応答することで、リアルタイムオーソリがシンプルになり、タイムアウトが原因でオーソリ成功率を下げる可能性がある余分な API コールをなくせます。

新しい導入を構築する場合は、[direct webhook responses を使用できます](https://docs.stripe.com/issuing/controls/real-time-authorizations.md)。`/approve` API コールと `/decline` API コールを使用する既存の導入がある場合は、直接 Webhook 応答に移行できます。

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

## レガシー API コールフロー

これまでは、`issuing_authorization.request` Webhook に応答する前に、着信オーソリリクエストに対して `/approve` API コールまたは `/decline` API コールを行って決定する必要がありました。
 (See full diagram at https://docs.stripe.com/issuing/controls/real-time-authorizations/direct-webhook-migration)
## 新しい Webhook 直接応答フロー

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

この API について、詳細は[リアルタイムのオーソリに関するドキュメント](https://docs.stripe.com/issuing/controls/real-time-authorizations.md)をご覧いただき、[対話型ガイド](https://docs.stripe.com/issuing/controls/real-time-authorizations/quickstart.md)を参照してシステムを構築してください。
 (See full diagram at https://docs.stripe.com/issuing/controls/real-time-authorizations/direct-webhook-migration)
HTTP ステータスコード `200`、特定の API バージョンに設定された `Stripe-Version` ヘッダー、および JSON 本文のブール値 `approved` で応答する必要があります。JSON 本文は[指定の API バージョン](https://docs.stripe.com/api/versioning.md)に対応している必要があります。

管理可能な金額のオーソリでは、[部分的な承認](https://docs.stripe.com/issuing/purchases/authorizations.md?issuing-authorization-type=incremental_authorization#handling-other-authorizations)にオプションで `amount` を含めることができます。

### Webhook 直接応答 Authorization API の変更

Webhook の直接応答 [Authorization (オーソリ)](https://docs.stripe.com/api/issuing/authorizations/object.md) について、以下が追加されています。

- [request_history.reason](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-request_history-reason) に値 `webhook_error` が追加されました。この値は、Webhook レスポンスが検証エラーで失敗した場合に表示されます。
- 新しいフィールド `request_history.reason_message` が追加されました。このフィールドには、`request_history.reason` が `webhook_error` の場合に詳細なエラーメッセージが入ります。

## 直接応答への移行

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

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

以下のコードは、Ruby の場合に Webhook の直接応答への移行がどのようになるかを示す例です。他の言語については、[対話型ガイド](https://docs.stripe.com/issuing/controls/real-time-authorizations/quickstart.md)を参照してください。

```ruby
# User's existing API call webhook handling code, using Sinatra.
# In this example, the synchronous webhook and normal webhook share an endpoint.
client = Stripe::StripeClient.new(ENV.fetch('STRIPE_API_KEY'))
post '/webhook' do
  payload = request.body.read

  if event['type'] == 'issuing_authorization.request'
    auth = event['data']['object']
    # Approve with legacy API call.
    client.v1.issuing.authorizations.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
```

*サンドボックス* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes)環境でテストした後、トラフィックを徐々に直接 Webhook レスポンスに移行します。

```ruby
# User's API call and direct response webhook handling code, using Sinatra.
# In this example, the synchronous webhook and normal webhook share an endpoint.
client = Stripe::StripeClient.new(ENV.fetch('STRIPE_API_KEY'))
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.
      client.v1.issuing.authorizations.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
```