# Gérer les événements de paiement avec des webhooks

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 endpoint 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 tunnel de paiement, comme :

- Paiements réussis (`payment_intent.succeeded`)
- 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 webhook

Vous pouvez créer un gestionnaire de webhooks sur votre serveur pour gérer vos tunnels de paiement en ligne. Commencez par choisir un endpoint 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 endpoint de webhook

Ajoutez un nouvel endpoint à 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 nouvel endpoint, 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 Stripe

Installez la CLI Stripe avec [npm](https://www.npmjs.com/)&nbsp;:

```bash
npm install -g @stripe/cli@latest
```

Après l’installation, connectez-vous à votre compte Stripe&nbsp;:

```bash
stripe login
```

Après avoir installé la CLI, vous pouvez également installer [les outils d’agent](https://docs.stripe.com/cli/agent/setup) ou configurer l’[autocomplétion](https://docs.stripe.com/cli/completion).

> Pour plus d’options d’installation pour Windows, macOS, Linux et Docker, consultez le [fichier README de la CLI Stripe](https://github.com/stripe/stripe-cli#installation) sur GitHub.

## Tester votre webhook en local

Utilisez l’interface de ligne de commande (CLI) pour transmettre des événements à votre endpoint 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 `trigger` de la CLI 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&nbsp;!) apparaît dans l’onglet du terminal que votre serveur exécute.

## Optional: Vérifier la signature du webhook

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 endpoint 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 endpoint en local, utilisez la commande `trigger` pour obtenir la clé secrète de votre endpoint de webhook à partir de l’interface de ligne de commande.

```bash
stripe listen
```

La clé secrète du endpoint 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 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 endpoint de webhook

Pour mettre en production votre endpoint de webhook, vous devez procéder comme suit&nbsp;:

1. Utilisez vos [clés API de production](https://docs.stripe.com/keys.md#test-live-modes) et non pas vos clés de test.
2. Configurez votre endpoint webhook dans [Workbench](https://docs.stripe.com/workbench.md) ou avec l’API.
3. Pour configurer votre endpoint dans Workbench, allez dans l’[onglet Webhooks](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 **Endpoint Webhook** dans la liste des types de destination disponibles. Cliquez sur **Continuer** et entrez l’URL de votre endpoint, un nom optionnel et une description optionnelle. Cliquez sur **Créer une destination**.
5. Remplacez la clé du endpoint webhook dans votre application par le nouveau secret affiché dans la vue des détails de destination dans Workbench pour votre endpoint.

Votre application peut désormais accepter des événements en mode production. Pour plus d’informations sur la configuration de votre endpoint de webhook, consultez l’API [Webhook Endpoint](https://docs.stripe.com/api/webhook_endpoints.md). Pour effectuer des tests dans un environnement de test, [consultez notre guide de développement](https://docs.stripe.com/webhooks.md).