Recevoir des événements Stripe dans votre endpoint de webhook

Lors de la création d’intégrations Stripe, il est possible que vous souhaitiez que vos applications reçoivent les événements au fur et à mesure qu’ils se déclenchent dans vos comptes Stripe, afin que vos systèmes back-end exécutent 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 webhook est particulièrement utile pour écouter 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, l’aboutissement d’un paiement récurrent ou l’encaissement des paiements d’un abonnement.

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

Démarrer

Pour recevoir des événements webhook dans votre application :

1. Créez un gestionnaire de endpoints de webhook pour recevoir des requêtes POST de données d’événement.
2. Testez votre gestionnaire de endpoints de webhook à 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.

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

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 avec Stripe. Les endpoints de webhook enregistrés doivent être des URL HTTPS accessibles publiquement.

Format d’URL de webhook

Le 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énements.
3. Sélectionnez l’endroit 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.
4. Sélectionnez la version de l’API pour l’objet Events que vous souhaitez utiliser.
5. Sélectionnez les types d’événement que vous souhaitez envoyer à un endpoint de webhook.
6. Sélectionnez Continuer, puis endpoint de webhook comme type de destination.
7. 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 connexion réseau est intermittente.
• Votre endpoint de webhook ne reçoit pas les événements attendus.

Afficher les remises d’événements

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

L’onglet Événements fournit une liste d’événements et indique leur état : Delivered, Pending ou Failed. Cliquez sur un événement pour afficher Delivery attempts, qui inclut le code d’état HTTP des précédentes tentatives de remise et l’heure des remises à venir en attente.

Pour visualiser les tentatives de remise d’événements, ouvrez l’onglet Événements d’un endpoint de webhooks.

Corriger les codes d’état HTTP

Lorsqu’un événement affiche un code d’état 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

La version de l’API dans les paramètres de votre compte au moment de l’événement détermine sa version, et détermine ainsi la structure d’un Event envoyé à votre destination. Par exemple, si votre compte est défini sur une ancienne version d’API telle que celle du 16-02-2015 et que vous modifiez la version d’API pour une demande spécifique avec la gestion des versions, l’objet Event généré et envoyé à votre destination est toujours basé sur la version d’API du 16-02-2015. Vous ne pouvez pas modifier les objets Event après leur création. Par exemple, si vous mettez à jour un paiement, l’événement de paiement d’origine reste inchangé. Par conséquent, les mises à jour ultérieures de la version de l’API de votre compte ne modifient pas rétroactivement les objets Event existants. La récupération d’un ancien Event en appelant /v1/events à l’aide d’une version plus récente de l’API n’a pas non plus d’impact sur la structure de l’événement reçu. Vous pouvez définir les destinations des événements de test en fonction de votre version d’API par défaut ou de la dernière version d’API. L’objet Event envoyé à la destination est structuré en fonction de la version spécifiée pour la destination de l’événement.

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 à traiter les événements entrants avec une file d’attente asynchrone. Si vous choisissez de traiter les événements de manière synchrone, vous risquez de rencontrer des problèmes d’évolutivité. Une hausse importante des remises de webhooks (en début de mois par exemple, lors du renouvellement des abonnements) peut submerger vos hôtes de endpoints.

Les files d’attente asynchrones vous permettent de traiter les événements simultanés à un rythme que votre système adapté à votre système.

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érifier que les événements sont envoyés par 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 de webhook pour vous assurer que les événements reçus sont bien envoyés par Stripe. Stripe signe les événements webhook envoyés vers vos endpoints en incluant une signature dans l’en-tête Stripe-Signature de chaque événement. Cela 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 manuellement en utilisant 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évenir les 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 de votre serveur est correcte et synchronisée avec celle 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.