Recevez les événements Stripe dans votre endpoint de webhook

Lors de la création d’intégrations Stripe, vous pouvez souhaiter que vos applications reçoivent les événements au fur et à mesure qu’ils se produisent dans vos comptes Stripe, afin que vos systèmes back-end puissent exécuter des actions en conséquence.

Créez une destination d’événement pour recevoir des événements à un endpoint de webhook HTTPS. Une fois que vous avez enregistré l’endpoint de webhook, Stripe peut transmettre des données d’événement en temps réel à l’endpoint de webhook de votre application lorsque des événements surviennent sur votre compte Stripe. Stripe utilise HTTPS pour envoyer des événements de webhook à votre application en tant que charge utile JSON qui inclut un objet Event.

La réception d’événements de webhook vous aide à répondre à des événements asynchrones tels que la confirmation d’un paiement par la banque d’un client, la contestation d’un paiement par un client ou l’aboutissement d’un paiement récurrent.

Vous pouvez également recevoir des événements dans Amazon EventBridge avec des destinations d’événement.

Démarrer

Pour commencer à recevoir des événements de webhook dans votre application :

1. Créez un gestionnaire d’endpoint de webhook pour recevoir des requêtes POST de données d’événement.
2. Testez votre gestionnaire d’endpoint de webhook localement à l’aide de la CLI Stripe.
3. Créez une nouvelle destination d’événement pour votre endpoint de webhook.
4. Sécurisez votre endpoint de webhook.

Vous pouvez enregistrer et créer un endpoint pour gérer plusieurs types d’événements en même temps, ou configurer des endpoints individuels pour des événements spécifiques.

Comportements de type d’événement non pris en charge pour les destinations d’événements d’organisation

Stripe envoie la plupart des types d’événements de manière asynchrone ; cependant, pour certains types d’événements, Stripe attend une réponse. La présence ou l’absence d’une réponse de la part de la destination d’événements influence directement les actions de Stripe concernant ces types d’événements spécifiques.

Les destinations d’organisation offrent une prise en charge limitée des types d’événements qui nécessitent une réponse :

• Vous ne pouvez pas vous abonner à issuing_authorization.request pour les destinations d’organisation. Configurez plutôt un endpoint de webhook sur un compte Stripe au sein de l’organisation pour vous abonner à ce type d’événement. Utilisez issuing_authorization.request pour autoriser les demandes d’achat en temps réel.
• Vous pouvez vous abonner à checkout_sessions.completed pour les destinations d’organisation. Cependant, cela ne prend pas en compte le comportement de redirection lorsque vous intégrez Checkout directement dans votre site Web ou que vous redirigez les clients vers une page de paiement hébergée par Stripe. L’envoi d’un événement checkout_sessions.completed vers une destination d’organisation n’affecte pas le comportement de redirection. Pour influencer le comportement de redirection Checkout, traitez ce type d’événement avec un endpoint de webhook configuré sur un compte Stripe au sein de l’organisation.
• Vous pouvez vous abonner à invoice.created pour les destinations d’organisation. Toutefois, l’échec de la réponse à cet événement n’a aucune influence sur la finalisation automatique de la facture lors de l’utilisation du recouvrement automatique. Pour influencer la finalisation automatique des factures par le biais des réponses d’endpoint de webhook, traitez ce type d’événement avec un endpoint de webhook configuré dans un compte Stripe au sein de l’organisation.

require 'json'

# Using Sinatra
post '/webhook' do
  payload = request.body.read
  event = nil

  begin
    event = Stripe::Event.construct_from(
      JSON.parse(payload, symbolize_names: true)
    )
  rescue JSON::ParserError => e
    # Invalid payload
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'payment_intent.succeeded'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    # Then define and call a method to handle the successful payment intent.
    # handle_payment_intent_succeeded(payment_intent)
  when 'payment_method.attached'
    payment_method = event.data.object # contains a Stripe::PaymentMethod
    # Then define and call a method to handle the successful attachment of a PaymentMethod.
    # handle_payment_method_attached(payment_method)
  # ... handle other event types
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end

require 'json'

# Using Sinatra
post '/webhook' do
  payload = request.body.read
  event = nil

  begin
    event = Stripe::Event.construct_from(
      JSON.parse(payload, symbolize_names: true)
    )
  rescue JSON::ParserError => e
    # Invalid payload
    status 400
    return
  end

  # Extract the context
  context = event.context

  # Define your API key variables (ideally loaded securely)
  ACCOUNT_123_API_KEY = "sk_test_123"
  ACCOUNT_456_API_KEY = "sk_test_456"

  account_api_keys = {
    "account_123" => ACCOUNT_123_API_KEY,
    "account_456" => ACCOUNT_456_API_KEY
  }

  api_key = account_api_keys[context]

  if api_key.nil?
    puts "No API key found for context: #{context}"
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'customer.created'
    customer = event.data.object

    begin
      latest_customer = Stripe::Customer.retrieve(
        customer.id,
        { api_key: api_key }
      )
      handle_customer_created(latest_customer, context)
    rescue => e
      puts "Error retrieving customer: #{e.message}"
      status 500
      return
    end

  when 'payment_method.attached'
    payment_method = event.data.object

    begin
      latest_payment_method = Stripe::PaymentMethod.retrieve(
        payment_method.id,
        { api_key: api_key }
      )
      handle_payment_method_attached(latest_payment_method, context)
    rescue => e
      puts "Error retrieving payment method: #{e.message}"
      status 500
      return
    end

  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end

stripe listen --forward-to localhost:4242/webhook

stripe listen --events payment_intent.created,customer.created,payment_intent.succeeded,checkout.session.completed,payment_intent.payment_failed \
  --forward-to localhost:4242/webhook

stripe listen --load-from-webhooks-api --forward-to localhost:4242/webhook

Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)

stripe trigger payment_intent.succeeded
Running fixture for: payment_intent
Trigger succeeded! Check dashboard for event details.

Enregistrer votre endpoint

Après avoir testé la fonction de votre endpoint de webhook, utilisez l’API ou l’onglet Webhooks de Workbench pour enregistrer l’URL accessible de votre endpoint de webhook afin que Stripe sache où envoyer les événements. Vous pouvez enregistrer jusqu’à 16 endpoints de webhook sur Stripe. Les endpoints de webhook enregistrés doivent être des URL HTTPS accessibles au public.

Format d’URL de webhook

L’endpoint de webhook doit être enregistré avec le format d’URL suivant :

https://<your-website>/<your-webhook-endpoint>

Par exemple, si votre domaine est https://mycompanysite.com et que le chemin vers votre endpoint de webhook est @app.route('/stripe_webhooks', methods=['POST']), spécifiez https://mycompanysite.com/stripe_webhooks comme URL d’endpoint.

Créer une destination d’événement pour votre endpoint de webhook

Créez une destination d’événement à l’aide de Workbench dans le Dashboard ou par programmation avec l’API. Vous pouvez enregistrer jusqu’à 16 destinations d’événements sur chaque compte Stripe.

Dashboard

API

Pour créer un nouvel endpoint de webhook dans le Dashboard :

1. Ouvrez l’onglet Webhooks dans Workbench.
2. Cliquez sur Créer une destination d’événement.
3. Sélectionnez l’emplacement d’où vous souhaitez recevoir les événements. Stripe prend en charge deux types de configurations : Votre compte et Comptes connectés. Sélectionnez Compte pour écouter les événements de votre propre compte. Si vous avez créé une application Connect et que vous souhaitez écouter les événements de vos comptes connectés, sélectionnez Comptes connectés.

Écouter les événements à partir d'un endpoint de webhook d'organisation

Si vous créez un endpoint de webhook dans un compte d’organisation, sélectionnez Comptes pour écouter les événements des comptes de votre organisation. Si des plateformes Connect figurent parmi les membres de vos organisations et que vous souhaitez écouter les événements de tous les comptes connectés des plateformes, sélectionnez Comptes connectés.

1. Sélectionnez la version de l’API pour l’objet Events que vous souhaitez utiliser.
2. Sélectionnez les types d’événement que vous souhaitez envoyer à un endpoint de webhook.
3. Sélectionnez Continuer, puis endpoint de webhook comme type de destination.
4. Cliquez sur Continuer, puis renseignez l’URL de l’endpoint ainsi qu’une description facultative du webhook.

Enregistrer un nouveau webhook à l’aide de l’onglet Webhooks

Remarque

Workbench remplace le Dashboard des développeurs existant. Si vous utilisez encore le Dashboard des développeurs, découvrez comment créer un nouvel endpoint de webhook.

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

require 'stripe'
require 'sinatra'

# If you are testing your webhook locally with the Stripe CLI you
# can find the endpoint's secret by running `stripe listen`
# Otherwise, find your endpoint's secret in your webhook settings in
# the Developer Dashboard
endpoint_secret = 'whsec_...'

# Using the Sinatra framework
set :port, 4242

post '/my/webhook/url' do
  payload = request.body.read
  sig_header = request.env['HTTP_STRIPE_SIGNATURE']
  event = nil

  begin
    event = Stripe::Webhook.construct_event(
      payload, sig_header, endpoint_secret
    )
  rescue JSON::ParserError => e
    # Invalid payload
    puts "Error parsing payload: #{e.message}"
    status 400
    return
  rescue Stripe::SignatureVerificationError => e
    # Invalid signature
    puts "Error verifying webhook signature: #{e.message}"
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'payment_intent.succeeded'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    puts 'PaymentIntent was successful!'
  when 'payment_method.attached'
    payment_method = event.data.object # contains a Stripe::PaymentMethod
    puts 'PaymentMethod was attached to a Customer!'
  # ... handle other event types
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end

Déboguer des intégrations de webhooks

Plusieurs types de problèmes peuvent survenir lors de la remise d’événements à votre endpoint de webhook :

• Il est possible que Stripe ne parvienne pas à remettre un événement à votre endpoint de webhook.
• Votre endpoint de webhook comporte peut-être une erreur SSL.
• Votre connectivité réseau est intermittente.
• Votre endpoint de webhook ne reçoit pas les événements attendus.

Afficher les événements remis

Pour afficher les remises d’événements, sélectionnez l’endpoint de webhook dans l’onglet Webhooks, puis sélectionnez l’onglet Événements.

The Events tab provides a list of events and whether they’re Delivered, Pending, or Failed. Click an event to view metadata, including the HTTP status code of the delivery attempt and the time of pending future deliveries.

Corriger les codes d’état HTTP

Quand un événement affiche un code d’état de 200, cela indique qu’il a bien été remis au endpoint de webhook. Vous pouvez aussi recevoir un code d’état autre que 200. La liste ci-après détaille les codes d’état fréquents pour le protocole HTTPS, ainsi que les solutions préconisées.

Comportements de remise d’événements

Cette section vous aide à comprendre les différents comportements auxquels vous pouvez vous attendre concernant la manière dont Stripe envoie des événements à votre endpoint de webhook.

Retentatives automatiques

Stripe tente de livrer des événements à votre destination pendant un maximum de trois jours avec un recul exponentiel en mode production. Le cas échéant, vous pouvez voir quand la prochaine tentative aura lieu dans l’onglet Événements envoyés de votre destination d’événement. Les livraisons d’événements créées dans un environnement de test sont relancées trois fois en l’espace de quelques heures. Si votre destination a été désactivée ou supprimée lorsque nous effectuons une nouvelle tentative de remise, nous annulons toute relance ultérieure de cet événement. Toutefois, si vous désactivez puis réactivez la destination de l’événement avant que nous ne puissions effectuer la relance, les tentatives ultérieures seront toujours visibles.

Retentatives manuelles

There are two ways to manually retry events:

• In the Stripe Dashboard, click Resend when looking at a specific event. This works for up to 15 days after the event creation.
• With the Stripe CLI, run the stripe events resend <event_id> --webhook-endpoint=<endpoint_id> command. This works for up to 30 days after the event creation.

Ordre des événements

Stripe ne garantit pas la remise des événements dans l’ordre dans lequel ils ont été générés. Par exemple, la création d’un abonnement peut générer les événements suivants :

• customer.subscription.created
• invoice.created
• invoice.paid
• charge.created (si un paiement a lieu)

Assurez-vous que la destination de votre événement ne dépend pas de la réception des événements dans un ordre spécifique. Soyez prêt à gérer correctement leur livraison. Vous pouvez également utiliser l’API pour récupérer les éventuels objets manquants. Par exemple, vous pouvez récupérer les objets invoice, charge et subscription avec les informations de invoice.paid si vous recevez cet événement en premier.

Gestion des versions de l’API

The API version in your account settings when the event occurs dictates the API version, and therefore the structure of an Event sent to your destination. For example, if your account is set to an older API version, such as 2015-02-16, and you change the API version for a specific request with versioning, the Event object generated and sent to your destination is still based on the 2015-02-16 API version. You can’t change Event objects after creation. For example, if you update a charge, the original charge event remains unchanged. As a result, subsequent updates to your account’s API version don’t retroactively alter existing Event objects. Retrieving an older Event by calling /v1/events using a newer API version also has no impact on the structure of the received event. You can set test event destinations to either your default API version or the latest API version. The Event sent to the destination is structured for the event destination’s specified version.

Bonnes pratiques pour l’utilisation des webhooks

Passez en revue ces bonnes pratiques pour vous assurer que vos webhooks restent sécurisés et fonctionnent bien avec votre intégration.

Gérer les événements en double

Les endpoints de webhook peuvent parfois recevoir plusieurs fois le même événement. Vous pouvez vous prémunir contre ce phénomène en enregistrant l’ID des événements que vous avez traités, puis ignorer les événements déjà enregistrés.

Dans certains cas, deux objets Event distincts sont générés et envoyés. Pour identifier ces doublons, utilisez l’ID de l’objet dans data.object ainsi que le type d’événement (event.type).

Écouter uniquement les types d’événements requis par votre intégration

Configurez vos endpoints de webhook de sorte à ne recevoir que les types d’événements requis par votre intégration. L’écoute d’événements supplémentaires (ou de tous les événements) alourdit inutilement la charge de votre serveur, c’est pourquoi nous vous déconseillons cette pratique.

Vous pouvez modifier les événements qu’un endpoint de webhook reçoit dans le Dashboard ou à l’aide de l’API.

Gérer les événements de manière asynchrone

Configurez votre gestionnaire de façon à ce qu’il traite les événements entrants avec une file d’attente asynchrone. Vous pouvez rencontrer des problèmes d’évolutivité si vous choisissez de traiter les événements de manière synchrone. Tout pic important d’envoi de webhooks (par exemple, au début du mois, lorsque tous les abonnements sont renouvelés) peut submerger vos hôtes d’endpoint.

Les files d’attente asynchrones vous permettent de traiter les événements simultanés à une vitesse que votre système peut prendre en charge.

Exempter la route des webhooks de la protection CSRF

Si vous utilisez Rails, Django ou une autre infrastructure Web, il est possible que votre site vérifie automatiquement que chaque requête POST contient un token CSRF. Il s’agit d’une fonctionnalité de sécurité importante qui vous protège, vous et vos utilisateurs, contre les tentatives de falsification de requêtes intersites. Cependant, cette mesure de sécurité peut également empêcher votre site de traiter des événements légitimes. Dans ce cas, vous devrez peut-être retirer la protection CSRF du chemin des webhooks.

class StripeController < ApplicationController
  # If your controller accepts requests other than Stripe webhooks,
  # you'll probably want to use `protect_from_forgery` to add CSRF
  # protection for your application. But don't forget to exempt
  # your webhook route!
  protect_from_forgery except: :webhook

  def webhook
    # Process webhook data in `params`
  end
end

Recevoir des événements sur un serveur HTTPS

Si vous utilisez une URL HTTPS pour votre endpoint de webhook (obligatoire en mode production), Stripe vérifie que la connexion à votre serveur est sécurisée avant d’envoyer les données de votre webhook. Pour que ce processus fonctionne, votre serveur doit être configuré de sorte à prendre en charge le protocole HTTPS et disposer d’un certificat valide. Les webhooks de Stripe prennent uniquement en charge les versions de TLS v1.2 et v1.3.

Invalider régulièrement les clés secrètes de signature des endpoints

La clé secrète utilisée pour vérifier que les événements proviennent de Stripe peut être modifiée dans la section Webhooks de Workbench. Pour assurer leur sécurité, nous vous recommandons d’invalider (changer) les clés secrètes à intervalles réguliers ou lorsque vous soupçonnez que l’une d’entre elles est compromise.

Pour invalider une clé secrète :

1. Dans l’onglet Webhooks de Workbench, cliquez sur chaque endpoint dont vous souhaitez invalider la clé secrète.
2. Accédez au menu déroulant () et cliquez sur Invalider la clé secrète. Vous pouvez choisir de faire expirer immédiatement la clé secrète actuelle ou de retarder son expiration de 24 heures (maximum) pour vous laisser le temps de mettre à jour le code de vérification sur votre serveur. Dans l’intervalle, plusieurs clés secrètes seront actives pour le endpoint concerné. Stripe génère une signature par clé secrète jusqu’à son expiration.

Vérifiez que les événements sont envoyés depuis Stripe

Stripe envoie des événements webhook à partir d’une liste définie d’adresses IP. Ne faites confiance qu’aux événements provenant de ces adresses IP.

Vérifiez également les signatures des webhooks pour confirmer que Stripe a bien envoyé les événements reçus. Stripe signe les événements de webhook qu’il envoie à vos endpoints en incluant une signature dans l’en-tête Stripe-Signature de chaque événement. Ceci vous permet de vérifier que les événements ont été envoyés par Stripe, et non par un tiers. Vous pouvez vérifier les signatures soit à l’aide de nos bibliothèques officielles, soit manuellement à l’aide de votre propre solution.

La section suivante décrit comment vérifier les signatures de webhook :

1. Récupérez la clé secrète de votre endpoint.
2. Vérifiez la signature.

Récupérer la clé secrète de votre endpoint

Utilisez Workbench et accédez à l’onglet Webhooks pour afficher tous vos endpoints. Sélectionnez un endpoint pour lequel vous souhaitez obtenir la clé secrète, puis cliquez sur Cliquer pour révéler.

Stripe génère une clé secrète unique pour chaque endpoint. Si vous utilisez le même endpoint pour les clés API de test et de production, la clé secrète est différente pour chacune d’elles. En outre, si vous utilisez plusieurs endpoints, vous devez obtenir une clé secrète pour chacun de ceux dont vous souhaitez vérifier les signatures. Une fois cette configuration terminée, Stripe commence à signer chaque webhook qu’il envoie à l’endpoint.

Prévention des attaques par rejeu

Une attaque par rejeu se produit lorsqu’un attaquant intercepte une charge utile valide et sa signature, puis les retransmet. Pour limiter ce type d’attaques, Stripe inclut un horodatage dans l’en-tête Stripe-Signature. Comme cet horodatage fait partie de la charge utile signée, il est également vérifié par la signature. Un attaquant ne peut donc pas modifier l’horodatage sans invalider la signature. Si la signature est valide mais que l’horodatage est trop ancien, votre application peut refuser la charge utile.

Nos bibliothèques ont une tolérance par défaut de 5 minutes entre l’horodatage et l’heure actuelle. Vous pouvez modifier cette tolérance en fournissant un paramètre supplémentaire lors de la vérification des signatures. Utilisez le protocole Network Time Protocol (NTP) pour vous assurer que l’heure indiquée par l’horloge de votre serveur est correcte et synchronisée avec l’heure des serveurs de Stripe.

Stripe génère l’horodatage et la signature chaque fois que nous envoyons un événement à votre endpoint. Si Stripe tente à nouveau de transmettre un événement (par exemple, si votre endpoint a précédemment répondu avec un code d’état autre que 2xx), nous générons une nouvelle signature et un nouvel horodatage pour la nouvelle tentative de remise.

Renvoyer rapidement une réponse 2xx

Votre endpoint doit renvoyer rapidement un code d’état réussi (2xx) avant le déclenchement de toute logique complexe qui pourrait provoquer une expiration du délai imparti. Par exemple, vous devez renvoyer une réponse 200 avant de mettre à jour la facture d’un client comme payée dans votre système comptable.