Auf direkte Webhook-Antwort umstellen

Sie können jetzt mit einer Entscheidung per Echtzeitautorisierung direkt auf einen issuing_authorization.request-Webhook reagieren, anstatt während des Webhooks mit einem API-Aufruf Endpoints zu genehmigen und abzulehnen.

Eine direkte Reaktion auf das Webhook-Ereignis vereinfacht die Echtzeitautorisierung und entfernt einen zusätzlichen API-Aufruf, der sich durch Zeitüberschreitungen negativ auf Ihre Autorisierungsquote auswirken kann.

If you’re building a new integration, use the new direct webhook response instead of making approve and decline API calls. We’re deprecating the approve and decline endpoints, but existing users will continue to have access until at least the end of 2024. If you have an existing integration with real-time authorization, plan to migrate to direct webhook responses.

Aufruf von älteren APIs

Bisher mussten Sie einen API-Aufruf durchführen, um eine Autorisierung zu /approve oder /decline und so eine Entscheidung für eine eingehende Autorisierungsanfrage zu treffen. Erst dann konnten Sie auf den issuing_authorization.request-Webhook antworten.

Neuer direkter Webhook-Antwortablauf

Sie können jetzt mit einer Entscheidung im Antworttext direkt auf den Webhook issuing_authorization.request antworten, ohne einen separaten API-Aufruf durchführen zu müssen. Nach der Entscheidung wird weiterhin ein Webhook-Ereignis des Typs issuing_authorization.created oder issuing_authorization.updated gesendet.

Erfahren Sie mehr über diese API in der Dokumentation zu Echtzeitautorisierungen und erstellen Sie mit unserem interaktivem Leitfaden eine Integration.

Sie müssen mit dem HTTP-Statuscode 200, dem Header Stripe-Version mit einer bestimmten API-Version und dem booleschen Wert approved im JSON-Text antworten. Der JSON-Text muss der angegebenen API-Version entsprechen.

Bei Autorisierungen mit kontrollierbarem Betrag enthalten teilweise Genehmigungen optional den Parameter amount.

Direkte Webhook-Änderungen an der Authorization API

Für die direkte Webhook-Antwort Authorizations haben wir mehrere Ergänzungen vorgenommen:

• Der Wert webhook_error wurde zu request_history.reason hinzugefügt. Dieser Wert ist vorhanden, wenn die Webhook-Antwort aufgrund von Validierungsfehlern fehlschlägt.
• Neues Feld request_history.reason_message, das eine detaillierte Fehlermeldung enthält, wenn request_history.reason webhook_error ist.

Auf Direct Response umstellen

Sie können die direkte Webhook-Antwort in Testumgebungen ausprobieren. Als Best Practice empfehlen wir, schrittweise vom älteren API-Aufruf zur direkten Antwort auf den Webhook überzugehen.

Wenn Sie eine API-Methode aufrufen und den direkten Webhook-Antworttext einfügen, hat die Entscheidung über die API-Methode Vorrang.

Nachfolgend finden Sie ein Beispiel dafür, wie eine Migration zum direkten Webhook in Ruby aussehen könnte. Informationen zu anderen Sprachen finden Sie in unserem interaktiven Leitfaden.

# 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

Verlagern Sie den Datenverkehr nach dem Testen in einer Sandbox-Umgebung nach und nach auf die direkte Webhook-Antwort.

# 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