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 commencer à recevoir des événements webhook dans votre application, créez et enregistrez un endpoint de webhook :

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. Enregistrez votre endpoint auprès de Stripe à l’aide du Dashboard ou de l’API.
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é votre fonction endpoint de webhook, enregistrez l’URL accessible du endpoint de webhook à l’aide de la section Webhooks dans le Dashboard développeur ou de l’API 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 un nouvel endpoint de webhook

You can create new event destinations for webhook and AWS EventBridge destinations.

1. Open the Event destinations tab in Workbench.
2. Click Create new destination.
3. Select the API version for the events object you want to consume.
4. If you’re using Connect, you can listen for Events on connected accounts. Otherwise, choose Events on your account.
5. Select the event types that you want to send to the destination, then click Continue.
6. Select Webhook to send events to an HTTPS endpoint.
7. Provide the Endpoint URL for Stripe to send webhooks to and an optional description for the endpoint.
8. Click Create destination to create your webhook endpoint.

Note

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.

Enregistrer un endpoint de webhook avec l’API Stripe

Vous pouvez également créer des endpoints de webhook par programmation.

Pour recevoir des événements de comptes connectés, utilisez le paramètre connect.

L’exemple suivant crée un endpoint qui vous informe de l’aboutissement ou de l’échec d’un paiement.

Command Line

curl

curl https://api.stripe.com/v1/webhook_endpoints \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "url"="https://example.com/my/webhook/endpoint" \
  -d "enabled_events[]"="payment_intent.payment_failed" \
  -d "enabled_events[]"="payment_intent.succeeded"

# 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_4eC39HqLyjWDarjtT1zdp7dc'

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 événements remis à un endpoint spécifique, sélectionnez le endpoint de webhook dans l’onglet Webhooks.

Pour afficher tous les événements qui ont été déclenchés sur votre compte, affichez l’onglet Événements.

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.

Comportement des nouvelles tentatives

En mode production, Stripe tente de remettre un événement donné à votre endpoint de webhook pendant 3 jours maximum, avec un allongement exponentiel du délai entre chaque tentative. Dans la section Événements du Dashboard, vous pouvez voir à quel moment aura lieu la prochaine tentative.

En mode test, Stripe procède à 3 tentatives sur une période de quelques heures. Passé ce délai, vous pouvez retenter manuellement la transmission d’événements individuels à votre endpoint de webhook à l’aide de la section Événements du Dashboard. Vous pouvez également envoyer une requête portant sur les événements manqués pour rapprocher les données sur n’importe quelle période.

Les nouvelles tentatives automatiques se poursuivent, même si vous réessayez manuellement de transmettre des événements webhook individuels vers un endpoint donné et que la tentative aboutit.

Si votre endpoint est désactivé ou supprimé au moment où Stripe effectue une nouvelle tentative, les futures tentatives pour cet événement sont bloquées. Cependant, si vous désactivez puis réactivez un endpoint de webhook avant que Stripe ne puisse effectuer une nouvelle tentative, il est possible que d’autres tentatives aient lieu.

Désactiver le comportement

En mode test et en mode production, Stripe tente de vous informer par e-mail de l’existence d’un endpoint incorrectement configuré lorsque le endpoint ne répond pas par un code d’état HTTP 2xx pendant plusieurs jours d’affilée. Cet e-mail indique également que le endpoint sera désactivé automatiquement.

Gestion des versions de l’API

La version de l’API indiquée dans les paramètres de votre compte au moment de l’événement détermine la version de l’API et, par conséquent, la structure de l’objet Event envoyé dans un webhook. Par exemple, si votre compte utilise une ancienne version de l’API (16-02-2015 par exemple) et que vous modifiez la version de l’API pour une requête spécifique à l’aide de la gestion de version, l’objet Event généré et envoyé à votre endpoint reste basé sur la version 16-02-2015.

Vous ne pouvez pas modifier les objets Event une fois qu’ils ont été créés. Par exemple, si vous mettez à jour un paiement, l’événement de paiement initial reste inchangé. Cela signifie que les mises à jour apportées par la suite à la version de l’API de votre compte ne modifient pas de manière rétroactive les objets Event. La récupération d’événements plus anciens en appelant /v1/events à l’aide d’une version récente de l’API n’a pas non plus de conséquences sur la structure des événements reçus.

Vous pouvez configurer les endpoints de webhook de test sur votre version d’API par défaut ou sur la version la plus récente de l’API. L’Event envoyé à l’URL du webhook est structuré conformément à la version spécifiée pour l’endpoint. Vous pouvez également créer des endpoints par programmation avec une api_version spécifique.

Ordre des événements

Stripe ne garantit pas que les événements sont remis dans l’ordre dans lequel ils sont 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)

Les événements ne seront pas nécessairement remis à votre endpoint dans cet ordre précis. Vous devez en tenir compte. 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 à l’aide des informations contenues dans l’événement invoice.paid, si vous le recevez en premier).

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 du Dashboard. Pour chaque endpoint, cliquez sur Invalider la clé secrète. Vous pouvez choisir de faire expirer la clé secrète actuelle immédiatement ou de retarder son expiration jusqu’à 24 heures maximum pour vous permettre de mettre à jour le code de vérification sur votre serveur. Pendant cette période, plusieurs clés secrètes sont actives pour le endpoint. Stripe génère une signature par clé secrète jusqu’à son expiration. Pour assurer leur sécurité, nous vous recommandons d’invalider les clés secrètes à intervalles réguliers ou lorsque vous soupçonnez que l’une d’entre elles est compromise.

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 la section Webhooks du Dashboard. Sélectionnez un endpoint dont vous souhaitez obtenir la clé secrète et recherchez-le en haut à droite de la page.

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, et Stripe commencera alors à 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.