# Webhooks Connect

Découvrez comment utiliser les webhooks avec Connect pour recevoir des notifications liées à l'activité Stripe.

Stripe utilise des *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) pour informer votre application qu’un événement s’est produit sur votre compte. Toutes les intégrations *Connect* (Connect is Stripe's solution for multi-party businesses, such as marketplace or software platforms, to route payments between sellers, customers, and other recipients) doivent créer un [endpoint de webhook](https://dashboard.stripe.com/account/webhooks) chargé d’écouter les événements Connect.

## Webhooks Connect

Une plateforme Connect utilise deux types de webhooks :

- Les webhooks *Account* 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](https://docs.stripe.com/connect/authentication.md)). Cela inclut tous les types de paiements, à l’exception de ceux effectués directement sur un compte connecté.
- Les webhooks *Connect* sont destinés à l’activité des comptes connectés. Nous envoyons tous les événements du compte connecté (y compris les mises à jour de compte et les paiements directs) aux webhooks Connect.

Lorsque vous créez un webhook Connect, vous devez le configurer pour recevoir les événements de webhook Connect. Lorsque vous le créez dans [le Dashboard](https://dashboard.stripe.com/test/webhooks), sélectionnez **Écouter**, puis **Evénements sur les comptes connectés**. Lorsque vous le créez à l’aide du API, définissez le [paramètre connect](https://docs.stripe.com/api/webhook_endpoints/create.md#create_webhook_endpoint-connect) sur true.
![Paramètres des webhooks dans le Dashboard Stripe](https://b.stripecdn.com/docs-statics-srv/assets/webhooks.ac3d6c19a5281fbbd2b85a335cd887b3.png)

Pour les webhooks Connect, les URL de vos webhooks de développement ne reçoivent que des webhooks de test, tandis que vos URL de webhooks de production reçoivent à la fois des webhooks en mode production et des webhooks de test. En effet, vous pouvez effectuer des transactions en mode production et en mode test depuis une application en production. Nous vous recommandons de vérifier la valeur `livemode` lorsque vous recevez un webhook d’événement pour déterminer si les utilisateurs doivent effectuer une action.

Vous devez définir des endpoints webhook séparés pour vos comptes d’[environnement de test](https://docs.stripe.com/sandboxes.md) afin de recevoir les événements de ces comptes.

Chaque événement d’un compte connecté contient une propriété `account` de niveau supérieur qui identifie le compte connecté. Étant donné que le compte connecté est propriétaire de [l’objet qui a déclenché l’événement](https://docs.stripe.com/api/events/object.md#event_object-data-object), vous devez effectuer des requêtes API pour cet objet [en tant que compte connecté](https://docs.stripe.com/connect/authentication.md).

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

Le tableau suivant décrit certains des événements les plus courants et les plus importants liés aux comptes connectés :

| Événement                          | Type de data.object                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ---------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account.application.deauthorized` | `application`                                       | Se produit lorsqu’un compte connecté se déconnecte de votre plateforme. Vous pouvez l’utiliser pour déclencher un nettoyage sur votre serveur. Disponible pour les comptes connectés ayant accès au Dashboard Stripe, ce qui inclut les [comptes Standard](https://docs.stripe.com/connect/standard-accounts.md).                                                                                                                                                                                                                                                                                         |
| `account.external_account.updated` | Un compte externe, tel que `card` ou `bank_account` | Se produit lorsqu’[un compte bancaire associé ou une carte de débit associée à un compte connecté est modifié(e)](https://docs.stripe.com/connect/payouts-bank-accounts.md), ce qui peut avoir des conséquences sur les virements. Disponible pour les comptes connectés contrôlés par votre plateforme, comptes Custom et Express compris, et pour les comptes Standard dont les [contrôles de la plateforme](https://docs.stripe.com/connect/platform-controls-for-stripe-dashboard-accounts.md) sont activés.                                                                                          |
| `account.updated`                  | `account`                                           | Permet de surveiller les évolutions des exigences relatives aux comptes connectés et les changements d’état. Disponible pour tous les comptes connectés.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `balance.available`                | `balance`                                           | Se produit lorsque votre solde Stripe est mis à jour. Par exemple, lorsque les [fonds rechargés depuis votre compte bancaire](https://docs.stripe.com/connect/top-ups.md) sont disponibles pour un virement vers votre compte connecté.                                                                                                                                                                                                                                                                                                                                                                   |
| `payment_intent.succeeded`         | `payment_intent`                                    | Se produit lorsqu’un Payment Intent aboutit à un paiement réussi. Disponible pour tous les paiements, y compris les paiements de [destination](https://docs.stripe.com/connect/destination-charges.md) et [directs](https://docs.stripe.com/connect/direct-charges.md).                                                                                                                                                                                                                                                                                                                                   |
| `payout.failed`                    | `payout`                                            | Se produit quand [un virement échoue](https://docs.stripe.com/connect/payouts-connected-accounts.md#webhooks). Lorsqu’un virement échoue, le compte externe concerné est désactivé. Aucun virement automatique ou manuel ne peut être traité tant que le compte externe n’a pas été mis à jour.                                                                                                                                                                                                                                                                                                           |
| `person.updated`                   | `person`                                            | Se produit lorsqu’une `Person` associé au `Account` est modifiée. Si vous [utilisez l’API Persons pour gérer les exigences](https://docs.stripe.com/connect/handling-api-verification.md#verification-process), écoutez cet événement pour surveiller les évolutions des exigences et les changements d’état des personnes. Disponible pour les comptes connectés contrôlés par votre plateforme, comptes Custom et Express compris, et pour les comptes Standard dont les [contrôles de la plateforme](https://docs.stripe.com/connect/platform-controls-for-stripe-dashboard-accounts.md) sont activés. |

#### Événement - account.application.deauthorized

#### Ruby

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

set :port, 4242

# Don't put any keys in code. Use a secrets vault or environment
# variable to supply keys to your integration. This example
# shows how to set a secret key for illustration purposes only.
#
# See https://docs.stripe.com/keys-best-practices and find your
# keys at https://dashboard.stripe.com/apikeys.
Stripe.api_key = '<<YOUR_SECRET_KEY>>'

# If you're 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
```

#### Événement - account.updated

#### Ruby

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

set :port, 4242

# Don't put any keys in code. Use a secrets vault or environment
# variable to supply keys to your integration. This example
# shows how to set a secret key for illustration purposes only.
#
# See https://docs.stripe.com/keys-best-practices and find your
# keys at https://dashboard.stripe.com/apikeys.
Stripe.api_key = '<<YOUR_SECRET_KEY>>'

# If you're 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.updated'
    account = event['data']['object']
    handle_account_update(account)
  end

  status 200
end

def handle_account_update(account)
  # Collect more required information
  puts account.to_s
end
```

#### Événement - person.updated

#### Ruby

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

set :port, 4242

# Don't put any keys in code. Use a secrets vault or environment
# variable to supply keys to your integration. This example
# shows how to set a secret key for illustration purposes only.
#
# See https://docs.stripe.com/keys-best-practices and find your
# keys at https://dashboard.stripe.com/apikeys.
Stripe.api_key = '<<YOUR_SECRET_KEY>>'

# If you're 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'] == 'person.updated'
    person = event['data']['object']
    connected_account_id = event['account']
    handle_person_update(connected_account_id, person)
  end

  status 200
end

def handle_person_update(connected_account_id, person)
  # Collect more required information
  puts 'Connected account ID: ' + connected_account_id
  puts person.to_s
end
```

#### Événement - payment_intent.succeeded, direct charge

#### Ruby

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

set :port, 4242

# Don't put any keys in code. Use a secrets vault or environment
# variable to supply keys to your integration. This example
# shows how to set a secret key for illustration purposes only.
#
# See https://docs.stripe.com/keys-best-practices and find your
# keys at https://dashboard.stripe.com/apikeys.
Stripe.api_key = '<<YOUR_SECRET_KEY>>'

# 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'] == 'payment_intent.succeeded'
    payment_intent = event['data']['object']
    connected_account_id = event['account']
    handle_successful_payment_intent(connected_account_id, payment_intent)
  end

  status 200
end

def handle_successful_payment_intent(connected_account_id, payment_intent)
  # Fulfill the purchase
  puts 'Connected account ID: ' + connected_account_id
  puts payment_intent.to_s
end
```

#### Événement - payment_intent.succeeded, non-direct charge

#### Ruby

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

set :port, 4242

# Don't put any keys in code. Use a secrets vault or environment
# variable to supply keys to your integration. This example
# shows how to set a secret key for illustration purposes only.
#
# See https://docs.stripe.com/keys-best-practices and find your
# keys at https://dashboard.stripe.com/apikeys.
Stripe.api_key = '<<YOUR_SECRET_KEY>>'

# 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'] == 'payment_intent.succeeded'
    payment_intent = event['data']['object']
    handle_successful_payment_intent(payment_intent)
  end

  status 200
end

def handle_successful_payment_intent(payment_intent)
  # Fulfill the purchase
  puts payment_intent.to_s
end
```

#### Événement - balance.available

#### Ruby

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

set :port, 4242

# Don't put any keys in code. Use a secrets vault or environment
# variable to supply keys to your integration. This example
# shows how to set a secret key for illustration purposes only.
#
# See https://docs.stripe.com/keys-best-practices and find your
# keys at https://dashboard.stripe.com/apikeys.
Stripe.api_key = '<<YOUR_SECRET_KEY>>'

# If you're 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'] == 'balance.available'
    balance = event['data']['object']
    handle_available_balance(balance)
  end

  status 200
end

def handle_available_balance(balance)
  # Transfer funds to a connected account
  puts balance.to_s
end
```

#### Événement - account.external_account.updated

#### Ruby

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

set :port, 4242

# Don't put any keys in code. Use a secrets vault or environment
# variable to supply keys to your integration. This example
# shows how to set a secret key for illustration purposes only.
#
# See https://docs.stripe.com/keys-best-practices and find your
# keys at https://dashboard.stripe.com/apikeys.
Stripe.api_key = '<<YOUR_SECRET_KEY>>'

# If you're 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.external_account.updated'
    external_account = event['data']['object']
    connected_account_id = event['account']
    handle_external_account_update(connected_account_id, external_account)
  end

  status 200
end

def handle_external_account_update(connected_account_id, external_account)
  # Transfer funds to a connected account
  puts 'Connected account ID: ' + connected_account_id
  puts external_account.to_s
end
```

#### Événement - payout.failed

#### Ruby

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

set :port, 4242

# Don't put any keys in code. Use a secrets vault or environment
# variable to supply keys to your integration. This example
# shows how to set a secret key for illustration purposes only.
#
# See https://docs.stripe.com/keys-best-practices and find your
# keys at https://dashboard.stripe.com/apikeys.
Stripe.api_key = '<<YOUR_SECRET_KEY>>'

# If you're 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'] == 'payout.failed'
    payout = event['data']['object']
    connected_account_id = event['account']
    handle_failed_payout(connected_account_id, payout)
  end

  status 200
end

def handle_failed_payout(connected_account_id, payout)
  # Re-collect bank account required information
  puts 'Connected account ID: ' + connected_account_id
  puts payout.to_s
end
```

## Tester des webhooks en local

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

1. Si ce n’est pas déjà fait, [installez la Stripe CLI](https://docs.stripe.com/stripe-cli/install.md) sur votre machine.

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

1. 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` in one terminal window, and running `stripe trigger {{EVENT_NAME}}` dans une autre.

> Pour les webhooks Connect, utilisez [–forward-connect-to](https://docs.stripe.com/cli/listen#listen-forward-connect-to) avec `stripe listen` et [–stripe-account](https://docs.stripe.com/cli/trigger#trigger-stripe_account) avec `stripe trigger`.

## See also

- [Documentation relative aux webhooks](https://docs.stripe.com/webhooks.md)
- [Documentation relative à l’objet Event](https://docs.stripe.com/api.md#events)