# Handle payment events with webhooks

How to use webhooks to respond to offline payment events.

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('<<YOUR_SECRET_KEY>>')

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
Pour découvrir des méthodes d’installation supplémentaires, consultez la section [Démarrer avec l’interface de ligne de commande Stripe](https://docs.stripe.com/stripe-cli.md).
Une fois l’interface de ligne de commande de Stripe installée, exécutez `stripe login` dans la ligne de commande pour générer un code de jumelage afin d’y associer votre compte Stripe. Appuyez sur **Entrée** pour lancer votre navigateur et connectez-vous à votre compte Stripe afin d’autoriser l’accès. La clé API générée est valide pendant 90&nbsp;jours. Vous pouvez modifier ou supprimer la clé à la section [Clés API](https://dashboard.stripe.com/apikeys) du Dashboard.

> Vous pouvez créer une configuration spécifique à un projet en incluant l’indicateur [–project-name](https://docs.stripe.com/cli/login#login-project-name) lorsque vous vous connectez et lorsque vous exécutez des commandes pour ce projet.

Test

```bash
stripe login
Your pairing code is: humour-nifty-finer-magic
Press Enter to open up the browser (^C to quit)
```

Si vous souhaitez utiliser une clé API existante, utilisez l’indicateur `--api-key`&nbsp;:

```bash
stripe login --api-key <<YOUR_SECRET_KEY>>
Your pairing code is: humour-nifty-finer-magic
Press Enter to open up the browser (^C to quit)
```

## 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&nbsp;:

```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`&nbsp;:

```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('<<YOUR_SECRET_KEY>>')

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 Dashboardendpoint_secret = 'whsec_...'

# Using the Sinatra framework
set :port, 4242

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

  beginevent = 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&nbsp;:

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.
1. Configurez le point de terminaison de votre accroche web dans [Workbench](https://docs.stripe.com/workbench.md) ou avec l’API.
1. Pour configurer votre point de terminaison dans Workbench, rendez-vous dans l’[onglet Lien de rappel HTTP](https://dashboard.stripe.com/workbench/webhooks).
1. 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**.
1. 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).