Auf direkte Webhook-Antwort umstellen

Erfahren Sie, wie Sie Echtzeitautorisierungen in Issuing von API-Aufrufen auf direkte Webhook-Antworten 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.

Wenn Sie eine neue Integration erstellen, verwenden Sie die neue direkte Webhook-Antwort, anstatt API-Aufrufe zum Genehmigen oder Ablehnen zu tätigen. Die Endpoints für Genehmigungen und Ablehnungen werden eingestellt, aber bestehende Nutzer/innen haben noch bis mindestens Ende 2024 Zugriff. Wenn Sie über eine bestehende Integration mit Echtzeitautorisierung verfügen, sollten Sie die Migration zu direkten Webhook-Antworten planen.

Notiz

Dieser Leitfaden gilt nur, wenn Sie die /approve und /decline für Echtzeitautorisierungen verwenden.

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 im Testmodus ausprobieren. Als Best Practice empfehlen wir, schrittweise vom älteren API-Aufruf zur direkten Antwort an 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 im Testmodus 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