Migrer vers la méthode de réponse directe aux webhooks

Vous pouvez désormais répondre directement à un webhook issuing_authorization.request avec une décision d’autorisation en temps réel au lieu d’effectuer un appel à l’API pour approuver et refuser les endpoints pendant le webhook.

Répondre directement à l’événement webhook simplifie les autorisations en temps réel et supprime un appel à l’API supplémentaire qui peut avoir une incidence négative sur votre taux d’autorisation avec des expirations.

Si vous développez une nouvelle intégration, utilisez la nouvelle réponse de webhook directe au lieu d’effectuer des appels d’approbation ou de refus à l’API. Nous abandonnons les endpoints d’approbation et de refus, mais les utilisateurs existants pourront toujours y accéder au moins jusqu’à la fin de l’année 2024. Si vous disposez d’une intégration existante avec autorisation en temps réel, prévoyez de migrer vers les réponses de webhook directes.

Flux d’appels à l’ancienne API

Auparavant, vous deviez effectuer un appel à l’API à /approve ou /decline pour prendre une décision concernant une demande d’autorisation entrante avant de répondre au webhook issuing_authorization.request.

Nouveau flux de réponse direct pour les webhooks

Vous pouvez désormais répondre directement au webhook issuing_authorization.request avec une décision dans le corps de la réponse, sans avoir besoin d’effectuer un appel à l’API distinct. Une fois la décision prise, un événement webhook issuing_authorization.created ou issuing_authorization.updated est toujours envoyé.

Pour en savoir plus sur cette API, consultez la documentation relative aux autorisations en temps réel et créez une intégration avec notre guide interactif.

Vous devez répondre avec un code d’état HTTP 200, un en-tête Stripe-Version défini sur une version spécifique de l’API et une valeur booléenne approved dans le corps JSON. Le corps JSON doit correspondre à la version spécifiée de l’API.

Pour les autorisations à montant contrôlable, les approbations partielles incluent facultativement amount.

Modifications dans l’API d’autorisation du webhook direct

Pour les autorisations de réponse directe aux webhooks, nous avons effectué plusieurs ajouts :

• Ajout de la valeur webhook_error à request_history.reason. Cette valeur est présente si la réponse du webhook échoue en raison d’erreurs de validation.
• Nouveau champ request_history.reason_message, qui inclut un message d’erreur détaillé si la valeur de request_history.reason est webhook_error.

Migrer vers la réponse directe

Vous pouvez essayer la réponse directe du webhook dans les environnements de test. Au titre de bonne pratique, nous vous recommandons de passer progressivement de l’ancien appel à l’API à une réponse directe au webhook.

Si vous appelez une méthode API et incluez le corps de la réponse directe du webhook, la décision de la méthode API est prioritaire.

Voici un exemple de ce à quoi peut ressembler une migration vers le webhook direct dans Ruby. Pour les autres langues, consultez notre guide interactif.

# 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

Après avoir effectué des tests dans un environnement de test, transférez progressivement le trafic vers la réponse directe du 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