Webhooks Connect

Stripe utilise des webhooks pour informer votre application qu’un événement s’est produit sur votre compte. Toutes les intégrations Connect doivent créer un endpoint de webhook chargé d’écouter les événements Connect.

Webhooks Connect

Il existe différents types de webhooks :

• Les webhooks de compte sont destinés à l’activité de votre propre compte (par exemple la plupart des requêtes effectuées à l’aide de vos clés API et sans authentification en tant que compte Stripe tiers). Cette activité inclut tous les types de débits, à l’exception de ceux réalisés directement sur un compte connecté.
• Les webhooks Connect concernent l’activité de tout compte connecté. Tous les événements du compte connecté sont envoyés aux webhooks Connect, y compris l’événement important account.updated pour tout compte connecté et les paiements directs.

Lors de la création de votre webhook, assurez-vous qu’il est configuré de sorte à recevoir les événements webhook Connect. Pour ce faire, utilisez l’API et définissez le paramètre connect sur true lors de la création de l’endpoint de webhook ou utilisez le Dashboard.

Pour les webhooks Connect, alors que seuls les webhooks de test sont envoyés à vos URL de webhook de développement, vos URL de webhooks de production recevront à la fois les webhooks de test et les webhooks de production. En effet, vous pouvez effectuer des transactions à la fois en mode production et en mode test depuis une application en production. Ainsi, nous vous recommandons de vérifier la valeur livemode lorsque vous recevez un webhook d’événement afin de savoir quelle action, le cas échéant, il y a lieu de déclencher.

Comme indiqué dans la documentation relative à l’objet Event, chaque événement pour un compte connecté contient également une propriété account de niveau supérieur. Celle-ci indique le compte auquel le webhook est envoyé et le data[object] auquel il appartient. Dans la mesure où ces objets appartiennent à d’autres comptes, vous devez effectuer des requêtes à l’API au nom du compte connecté concerné pour pouvoir y accéder.

{
  "id": 
"{{EVENT_ID}}",
  "livemode": true,
  "object": "event",
  "type": "customer.created",
  "account": 
"{{CONNECTED_ACCOUNT_ID}}",
  "pending_webhooks": 2,
  "created": 1349654313,
  "data": {...}
}

Stripe recommande d’écouter plusieurs événements liés aux comptes :

# Using Sinatra.
require 'sinatra'
require 'stripe'

set :port, 4242

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

# 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_...'

post '/webhook' do
  payload = request.body.read
  sig_header = request.env['HTTP_STRIPE_SIGNATURE']

  event = nil

  # Verify webhook signature and extract the event.
  # See https://stripe.com/docs/webhooks#verify-events for more information.
  begin
    event = Stripe::Webhook.construct_event(
      payload, sig_header, endpoint_secret
    )
  rescue JSON::ParserError => e
    # Invalid payload.
    status 400
    return
  rescue Stripe::SignatureVerificationError => e
    # Invalid Signature.
    status 400
    return
  end

  if event['type'] == 'account.application.deauthorized'
    application = event['data']['object']
    connected_account_id = event['account']
    handle_deauthorization(connected_account_id, application)
  end

  status 200
end

def handle_deauthorization(connected_account_id, application)
  # Clean up account state.
  puts 'Connected account ID: ' + connected_account_id
  puts application.to_s
end

Les événements répertoriés ci-dessus sont ceux que nous recommandons généralement aux intégrations Connect d’écouter. Toutefois, de nombreux autres types d’événements peuvent présenter un intérêt.

Tester vos webhooks en local

Vous pouvez tester vos webhooks en local à l’aide de l’interface de ligne de commande Stripe.

1. Si vous ne l’avez pas encore fait, installez la CLI Stripe sur votre ordinateur.

2. Connectez-vous à votre compte Stripe et configurez l’interface de ligne de commande en exécutant la commande stripe login.

3. Autorisez votre hôte local à recevoir un événement simulé sur votre compte connecté en exécutant la commande stripe listen --forward-to localhost:{PORT}/webhook dans une fenêtre de terminal et la commande stripe trigger {{EVENT_NAME}} dans une autre.