# Gérer les événements de paiement avec des liens de rappel HTTP Comment utiliser les webhooks pour répondre à des événements de paiement hors ligne. Un *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) est un point de terminaison HTTP qui reçoit des événements de Stripe. Les webhooks vous permettent de recevoir des notifications à propos des événements qui surviennent en dehors de votre flux de paiement, comme : - Les paiements réussis (`payment_intent.succeeded`) - Les paiements contestés (`charge.dispute.created`) - Le solde créditeur dans votre compte Stripe (`balance.available`) Vous pouvez utiliser le Dashboard pour des actions ponctuelles telles que le remboursement d’un paiement ou la mise à jour des informations d’un client, tandis que les webhooks vous aident à faire évoluer votre intégration des paiements et à traiter de gros volumes d’événements critiques. ## Créer votre propre lien de rappel HTTP Vous pouvez créer un gestionnaire de webhooks sur votre serveur pour gérer vos flux de paiement en ligne. Commencez par choisir un point de terminaison pouvant recevoir des requêtes de Stripe et utilisez l’interface de ligne de commande pour tester votre intégration en local. Chaque requête de Stripe contient un objet [Event](https://docs.stripe.com/api/events/object.md) avec une référence à l’objet sur Stripe qui a été modifié. ## Créer un point de terminaison de lien de rappel HTTP Ajoutez un nouveau point de terminaison à votre application. Pour réagir à certains événements, consultez le champ `type` de l’objet de l’événement envoyé dans le corps de la requête. Ensuite, choisissez la sortie standard pour nous assurer que le webhook fonctionne. Après avoir ajouté votre nouveau point de terminaison, redémarrez le serveur. #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. client = Stripe::StripeClient.new('<>') require 'stripe' require 'sinatra' require 'json' # Using the Sinatra framework set :port, 4242 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 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 ``` ## Installer et configurer l'interface de ligne de commande de Stripe Installez l’interface de ligne de commande de Stripe avec [npm](https://www.npmjs.com/) : ```bash npm install --global @stripe/cli ``` > Pour connaître d’autres options d’installation sous Windows, macOS, Linux et Docker, consultez le fichier [Lisez-moi de Stripe CLI](https://github.com/stripe/stripe-cli#installation) sur GitHub. Une fois l’installation terminée, connectez l’interface de ligne de commande à votre compte Stripe en vous connectant : ```bash stripe login ``` L’interface de ligne de commande affiche un code d’appairage et ouvre le Dashboard Stripe, où vous pouvez approuver l’accès aux comptes, aux bacs à sable et au mode production. L’interface de ligne de commande stocke vos identifiants dans le magasin d’identifiants sécurisé de votre système d’exploitation (le cas échéant) et actualise automatiquement la session. Pour vous authentifier à l’aide d’une clé API à la place, exécutez `stripe login --interactive`, utilisez `stripe config`, passez l’option `--api-key` ou définissez la variable d’environnement `STRIPE_API_KEY`. ## Tester votre lien de rappel HTTP en local Utilisez l’interface de ligne de commande pour transmettre des événements à votre point de terminaison de webhook local à l’aide de la commande `listen`. Si votre application est exécutée sur le port 4242, exécutez : ```bash stripe listen --forward-to http://localhost:4242/webhook ``` Dans un autre onglet du terminal, utilisez la commande d’interface de ligne de commande `trigger` pour déclencher un événement de webhook fictif. ```bash stripe trigger payment_intent.succeeded ``` L’événement suivant apparaît dans l’onglet `listen` : ```bash [200 POST] OK payment_intent.succeeded ``` “PaymentIntent was successful!” (Le PaymentIntent a réussi!) apparaît dans l’onglet du terminal que votre serveur exécute. ## Optional: Vérifier la signature du lien de rappel HTTP Stripe inclut 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 à l’aide de nos bibliothèques officielles ou [les vérifier manuellement](https://docs.stripe.com/webhooks.md#verify-manually) avec votre propre solution. Tout d’abord, trouvez la clé secrète de votre point de terminaison de webhook et ajoutez-la à votre gestionnaire de webhook en tant que `endpoint_secret`. Puisque vous utilisez toujours l’interface de ligne de commande de Stripe pour développer votre point de terminaison en local, utilisez la commande `trigger` pour obtenir la clé secrète de votre point de terminaison de webhook à partir de l’interface de ligne de commande. ```bash stripe listen ``` La clé secrète du point de terminaison de webhook commence par `whsec_` suivi d’une série de chiffres et de lettres. Stockez cette clé secrète en lieu sûr et ne l’exposez jamais publiquement. #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. client = Stripe::StripeClient.new('<>') 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éployer votre point de terminaison de lien de rappel HTTP Pour mettre en production votre point de terminaison de webhook, vous devez procéder comme suit : 1. Utilisez vos [clés d’API en mode production](https://docs.stripe.com/keys.md#test-live-modes) et non vos clés de test. 2. Configurez le point de terminaison de votre accroche web dans [Workbench](https://docs.stripe.com/workbench.md) ou avec l’API. 3. Pour configurer votre point de terminaison dans Workbench, rendez-vous dans l’[onglet Lien de rappel HTTP](https://dashboard.stripe.com/workbench/webhooks). 4. Cliquez sur **Ajouter une destination** et entrez la version de l’API Stripe et les événements spécifiques que vous souhaitez que Stripe envoie. Cliquez sur **Continuer** et sélectionnez **¨Point de terminaison de l’accroche web** dans la liste des types de destinations disponibles. Cliquez sur **Continuer** et entrez l’URL de votre point de terminaison, le nom optionnel et la description optionnelle. Cliquez sur **Créer une destination**. 5. Remplacez le secret du point de terminaison de l’accroche web dans votre application par le nouveau secret indiqué dans la vue détaillée de la destination dans Workbench pour votre point de terminaison. Votre application est maintenant prête à accepter des événements en direct. Pour obtenir plus d’informations sur la configuration de votre point de terminaison de webhook, consultez l’API [Webhook Endpoint](https://docs.stripe.com/api/webhook_endpoints.md). Pour les tests dans un bac à sable, [consultez notre guide de développement](https://docs.stripe.com/webhooks.md).