Recevez des événements Stripe dans votre point de terminaison de webhook

Lors de la création d’intégrations Stripe, vous voudrez peut-être que vos applications reçoivent des événements au fur et à mesure qu’ils se produisent dans vos comptes Stripe, afin que vos systèmes dorsaux puissent exécuter des actions en conséquence.

Créez une destination d’événement pour recevoir des événements au niveau d’un point de terminaison webhook HTTPS. Après avoir enregistré un point de terminaison webhook, Stripe peut transmettre des données d’événements en temps réel au point de terminaison webhook de votre application lorsque des événements se produisent dans votre compte Stripe. Stripe utilise HTTPS pour envoyer des événements webhook à votre application sous forme de charge utile JSON qui comprend un objet Event.

La réception d’événements avec webhooks est particulièrement utile pour écouter les événements asynchrones comme lorsque l’institution financière d’un client confirme un paiement, lorsqu’un client conteste un paiement, lorsqu’un paiement récurrent est effectué ou les paiement d’abonnement sont encaissés.

Vous pouvez également recevoir des événements sur 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 point de terminaison webhook :

1. Créez un gestionnaire de point de terminaison de webhook pour recevoir des requêtes POST de données d’événement.
2. Testez votre gestionnaire de point de terminaison de webhook localement à l’aide de l’interface de ligne de commande Stripe.
3. Enregistrez votre point de terminaison dans Stripe à l’aide du Dashboard ou de l’API.
4. Sécurisez votre point de terminaison de webhook.

Vous pouvez enregistrer et créer un point de terminaison pour gérer plusieurs types d’événements simultanément, ou configurer des points de terminaison individuels pour des événements particuliers.

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 point de terminaison

Après avoir testé votre fonction de point de terminaison de webhook, enregistrez l’URL accessible du point de terminaison de webhook dans la section Webhooks du Dashboard du développeur ou de l’API afin d’indiquer à Stripe où envoyer les événements. Vous pouvez enregistrer jusqu’à 16 points de terminaison de webhook avec Stripe. Les points de terminaison de webhook enregistrés doivent contenir des URL HTTPS accessibles au public.

Format d’URL de webhook

Le format d’URL pour enregistrer un point de terminaison de webhook est le suivant :

https://<your-website>/<your-webhook-endpoint>

Par exemple, si votre domaine est https://mycompanysite.com et que le chemin vers votre point de terminaison de webhook est @app.route('/stripe_webhooks', methods=['POST']), précisez https://mycompanysite.com/stripe_webhooks comme l’URL du point de terminaison.

Créer un point de terminaison 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.

Remarques

Workbench remplace le Dashboard des développeurs existant. Si vous utilisez toujours le Dashboard des développeurs, découvrez comment créer un point de terminaison webhook.

Enregistrer un point de terminaison de webhook avec l’API Stripe

Vous pouvez également créer des points de terminaison de webhook par voie programmatique.

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

L’exemple suivant illustre la création d’un point de terminaison qui vous informe si le paiement a été effectué ou a échoué.

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 les intégrations de webhooks

Plusieurs types de problèmes peuvent survenir lors de l’envoi d’événements à votre point de terminaison de webhook :

• Il est possible que Stripe ne soit pas en mesure d’envoyer un événement à votre point de terminaison de webhook.
• Votre point de terminaison de webhook peut avoir un problème SSL.
• Votre connexion réseau est intermittente.
• Votre point de terminaison de webhook ne reçoit pas les événements que vous vous attendez à recevoir.

Afficher les événements envoyés

Pour afficher les événements envoyés pour un point de terminaison en particulier, sélectionnez le point de terminaison de webhook dans l’onglet Webhooks.

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

Corriger des codes d’état HTTP

Lorsqu’un événement affiche un code d’état de 200, il indique qu’un envoi a été effectué au point de terminaison de webhook. Vous pourriez également recevoir un code d’état autre que 200. Consultez le tableau ci-dessous pour obtenir une liste des codes d’état HTTP courants et des solutions recommandées.

Comportements d’envoi d’événements

Cette section vous aide à comprendre les différents comportements à attendre concernant la façon dont Stripe envoie les événements à votre point de terminaison de webhook.

Réessayer le comportement

En mode production, Stripe tente d’envoyer un événement donné à vos points de terminaison de webhook pendant un maximum de trois jours, avec un délai d’attente exponentiel. Vous pouvez consulter le moment de la prochaine relance dans la section Événements du Dashboard.

En mode test, Stripe procède à trois tentatives sur une période de quelques heures. Vous pouvez réessayer manuellement de transmettre des événements individuels à votre point de terminaison de webhook une fois ce délai écoulé à l’aide de la section Événements du Dashboard. Vous pouvez également envoyer une requête pour les événements manqués pour rapprocher les données sur n’importe quelle période.

Les tentatives automatiques se poursuivent, même si vous essayez de transmettre manuellement des événements de webhook individuels à un point de terminaison donné et que la tentative a fonctionné.

Si votre point de terminaison a été désactivé ou supprimé lorsque Stripe effectue une nouvelle tentative, toute relance ultérieure de cet événement sera annulée. Toutefois, si vous désactivez, puis réactivez un point de terminaison de webhook avant que Stripe ne puisse réessayer, des tentatives ultérieures seront toujours possibles.

Désactiver le comportement

En mode test et en mode production, Stripe essaie de vous informer par courriel de l’existence d’un point de terminaison configuré incorrectement lorsque le point de terminaison n’a pas envoyé de code d’état HTTP 2xx pendant plusieurs jours consécutifs. Ce courriel indique également le moment où le point de terminaison sera désactivé automatiquement.

Contrôle de version de l’API

Lorsque l’événement survient, la version de l’API dans les paramètres de votre compte dicte la version de l’API, et par extension la structure d’un objet Event envoyé dans un webhook. Par exemple, si votre compte utilise une ancienne version d’API, comme 2015-02-16, et que vous modifiez la version de l’API pour une requête spécifique avec le contrôle de version, l’objet Event généré et envoyé à votre point de terminaison est toujours fondé sur la version de l’API 2015-02-16.

Vous ne pouvez pas modifier les objets Event une fois qu’ils ont été créés. Par exemple, si un paiement est mis à jour, l’événement de paiement d’origine 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’anciens événements en effectuant un appel à /v1/events à l’aide d’une version récente de l’API n’a pas non plus de conséquence sur la structure des événements reçus.

Vous pouvez tester vos points de terminaison de webhook avec la version de l’API par défaut ou la version la plus récente. L’objet Event envoyé à l’URL du webhook est structuré en fonction de la version précisée pour le point de terminaison. Vous pouvez également créer des points de terminaison par voie programmatique avec un paramètre api_version spécifique.

Commande d’événements

Stripe ne garantit pas que les événements sont envoyés 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 existe)

Votre point de terminaison ne doit pas s’attendre à ce que ces événements soient envoyés dans cet ordre et doit donc gérer leur envoi en conséquence. 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 de l’événement invoice.paid si vous le recevez en premier).

Bonnes pratiques pour l’utilisation des webhooks

Passez en revue les bonnes pratiques suivantes pour vous assurer que vos webhooks restent sécurisés et fonctionnent correctement au sein de votre intégration.

Gérer les événements en double

Les points de terminaison Webhook peuvent parfois recevoir plusieurs fois le même événement. Vous pouvez vous prémunir contre ce phénomène en enregistrant les ID d’événements que vous avez traités et en ne traitant pas 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 avec event.type.

Écoutez uniquement les types d’événements nécessaires à votre intégration

Configurez vos points de terminaison de webhook de sorte à ne recevoir que les types d’événements nécessaires à 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 ne le recommandons pas.

Vous pouvez modifier les événements qu’un point de terminaison 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 pour traiter les événements entrants avec une file d’attente asynchrone. Vous pouvez rencontrer des problèmes d’évolutivité si vous choisissez de traiter les événements de manière synchrone. Toute augmentation importante des envois de webhooks (par exemple, au début du mois, lorsque tous les abonnements sont renouvelés) pourrait submerger les hôtes de vos points de terminaison.

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

Chemin de webhook exempté de la protection CSRF

Si vous utilisez Rails, Django ou un autre cadre Web, votre site peut vérifier automatiquement que chaque requête POST contient un jeton CSRF token. Cette mesure de sécurité importante vous protège vous et vos utilisateurs des tentatives de falsification de requête intersites. Toutefois, elle peut également empêcher votre site de traiter des événements légitimes. Dans ce cas, vous devrez peut-être exempter le chemin des webhooks de cette protection CSRF.

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 point de terminaison de webhook (obligatoire en mode production), Stripe vérifiera 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 de serveur valide. Les webhooks de Stripe prennent en charge uniquement le protocoleTLS, versions v.1.2 et v1.3.

Échangez périodiquement les clés secrètes de signature des points de terminaison

La clé secrète utilisée pour vérifier les événements venant de Stripe peut être modifiée dans la section Webhooks du Dashboard. Pour chaque point de terminaison, cliquez sur Échanger la clé secrète. Vous pouvez choisir de faire invalider 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. Pendant cette période, plusieurs clés secrètes sont actives pour le point de terminaison. Stripe génère une signature par clé secrète jusqu’à son expiration. Afin d’assurer leur sécurité, nous recommandons d’échanger périodiquement les clés secrètes ou de le faire lorsque vous soupçonnez que l’une d’entre elles a été compromise.

Vérifier que les événements sont envoyés par Stripe

Stripe envoie les événements de webhooks à partir d’une liste d’adresses IP prédéfinie. Ne faites confiance qu’aux événements prvenant de ces adresses IP.

De plus, vérifiez les signatures des webhooks pour confirmer que les événements reçus sont envoyés par Stripe. Stripe signe les événements de webhook qu’il envoie à vos points de terminaison 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 soit en utilisant nos bibliothèques officielles, soit en effectuant la vérification manuellement au moyen de 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 point de terminaison.
2. Vérifiez la signature.

Récupération de la clé secrète de votre point de terminaison

Utilisez la section Webhooks du Dashboard. Sélectionnez un point de terminaison pour lequel vous souhaitez obtenir la clé secrète et repérez la clé secrète en haut à droite de la page.

Stripe génère une clé secrète unique pour chaque point de terminaison. Si vous utilisez le même point de terminaison pour les clés API de test et de production, la clé secrète sera différente pour chacun. De plus, si vous utilisez plusieurs points de terminaison, vous devrez obtenir une clé secrète pour chaque point de terminaison dont vous voulez vérifier les signatures; Stripe commencera alors à signer chaque webhook envoyé au point de terminaison.

Prévention des attaques par réinsertion

Une attaque par réinsertion se produit lorsqu’un attaquant intercepte une charge utile valide et sa signature, puis les retransmet. Pour éviter ces attaques, Stripe inclut un horodatage dans l’en-tête Stripe-Signature. Étant donné que cet horodatage fait partie de la charge utile signée, il est également vérifié par la signature, de sorte qu’un attaquant ne peut pas modifier l’horodatage sans invalider la signature. Si la signature est valide, mais que l’horodatage est trop ancien, vous pouvez demander à votre application de rejeter la charge utile.

Nos bibliothèques ont une tolérance par défaut de cinq 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 de synchronisation de réseau (NTP) pour vous assurer que l’horloge de votre serveur est précise et synchronisée avec l’heure des serveurs de Stripe.

Stripe génère l’horodatage et la signature chaque fois que nous envoyons un événement à votre point de terminaison. Si Stripe tente à nouveau d’envoyer un événement (par exemple, si votre point de terminaison a précédemment répondu avec un code d’état autre que 2xx), nous générerons une nouvelle signature et un nouvel horodatage pour la nouvelle tentative d’envoi.

Renvoyer rapidement une réponse 2xx

Votre point de terminaison doit renvoyer rapidement un code d’état réussi (2xx) avant 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 étant payée dans votre système de comptabilité.