# Superviser les événements

Écouter les événements sur les comptes installés de vos utilisateurs

Les applications peuvent utiliser les [Webhooks](https://docs.stripe.com/webhooks.md) pour recevoir des alertes sur les événements qui se produisent sur les comptes de leurs utilisateurs. Cela permet aux développeurs d’applications de synchroniser les informations ou de déclencher des actions dans leur application lors d’un changement.

## Démarrer

1. [Gérez les événements webhook dans le back-end de votre application](https://docs.stripe.com/webhooks.md#webhook-endpoint-def).
2. [Enregistrez un endpoint de webhook](https://docs.stripe.com/webhooks.md) dans le Dashboard Stripe, et sélectionnez **Écouter les événements sur les comptes connectés**.
3. (Recommandé) Enregistrez des endpoints de webhook pour chaque environnement dans lequel les utilisateurs installent votre application : le mode production, l’environnement de test en mode test ou un environnement de test général. Pour les applications publiques installées dans un environnement de test général, [configurez les endpoints de webhook dans l’environnement de test géré de votre application](https://docs.stripe.com/stripe-apps/enable-sandbox-support.md#configure-webhook-events). Pour les applications privées, enregistrez les endpoints de webhook dans l’environnement où l’application est installée. Pour les applications publiques installées en mode production ou dans l’environnement de test en mode test, suivez les [règles d’acheminement des webhooks](https://docs.stripe.com/stripe-apps/handling-modes.md).
4. Ajoutez les autorisations nécessaires à votre application en exécutant `stripe apps grant permission` pour chacune d’entre elles.
   ```bash
   stripe apps grant permission "PERMISSION_NAME" "EXPLANATION"
   ```
Remplacez :
   - `PERMISSION_NAME` avec le nom de l’autorisation.
   - `EXPLANATION` avec une explication relative à l’autorisation d’accès. Les utilisateurs voient cette explication lorsqu’ils installent votre application.

Vous devez ajouter l’autorisation `event_read`, ainsi que toutes les autorisations associées aux événements spécifiques que vous souhaitez gérer. Pour plus d’informations sur les autorisations requises pour un événement particulier, consultez la rubrique [Autorisations pour les événements](https://docs.stripe.com/stripe-apps/reference/permissions.md#event-permissions).

Pour les événements d’installation, `livemode=false` indique une installation dans un environnement de test. Cela ne permet pas d’identifier le type d’environnement de test.

Par exemple, si vous souhaitez gérer les événements `payment_intent.succeeded` et `setup_intent.succeeded`, exécutez les commandes suivantes :

```bash
stripe apps grant permission "event_read" "Read webhook event data"
stripe apps grant permission "checkout_session_read" "Read Checkout Session data in webhook events"
stripe apps grant permission "payment_intent_read" "Read PaymentIntent data in webhook events"
stripe apps grant permission "setup_intent_read" "Read SetupIntent data in webhook events"
```

Après avoir exécuté ces commandes, le fichier du manifeste de votre application pourrait ressembler à ce qui suit :

```json
{
  "id": "com.example.app",
  "version": "1.2.3",
  "name": "Example App",
  "icon": "./example_icon_32.png",
  "permissions": [
    {
      "permission": "event_read",
      "purpose": "Read webhook event data"
    },
    {
      "permission": "checkout_session_read",
      "purpose": "Read Checkout Session data in webhook events"
    },
    {
      "permission": "payment_intent_read",
      "purpose": "Read PaymentIntent data in webhook events"
    },
    {
      "permission": "setup_intent_read",
      "purpose": "Read SetupIntent data in webhook events"
    }
  ]
}
```

## Surveiller les événements de votre compte

Pour recevoir les événements d’une application qui n’est accessible qu’aux utilisateurs de votre compte :

1. Gérez les [événements webhook](https://docs.stripe.com/webhooks.md#webhook-endpoint-def) dans le back-end de votre application.
2. [Enregistrez un endpoint de webhook](https://docs.stripe.com/webhooks.md) dans le Dashboard Stripe.

## Recevoir des notifications d’événement concernant votre application

Écoutez les événements (comme les installations et désinstallations des utilisateurs) sur votre application Stripe en utilisant des *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) entrants pour permettre à votre intégration de déclencher automatiquement des réactions sur votre back-end, telles que :

- La création de comptes utilisateur
- La mise à jour d’autorisations
- La désactivation d’un compte utilisateur et la suppression des données

Outre les [types d’événements pris en charge par Stripe](https://docs.stripe.com/api/events/types.md), les applications Stripe prennent en charge les événements suivants :

| Action du marchand | Événement webhook obtenu envoyé au back-end de l’application |
| --- | --- |
| Installez votre application | [apps.install.created](https://docs.stripe.com/api/events/types.md#event_types-apps.install.created) |
| Mettez à jour ou ré-autorisez votre application | [apps.install.updated](https://docs.stripe.com/api/events/types.md#event_types-apps.install.updated) |
| Désinstallez votre application | [apps.install.deleted](https://docs.stripe.com/api/events/types.md#event_types-apps.install.deleted) |

Stripe envoie également [account.appllication.authorized](https://docs.stripe.com/api/events/types.md#event_types-account.application.authorized) lorsqu’un compte connecte ou installe votre application, et [account.application.deauthorized](https://docs.stripe.com/api/events/types.md#event_types-account.application.deauthorized) lorsqu’un compte la déconnecte ou la désinstalle.

Stripe envoie chaque événement d’installation au développeur de l’application, au compte qui a installé l’application, et à la plateforme d’intégration qui a créé l’installation, le cas échéant. Pour une installation sur un autre compte, votre endpoint de webhook Connect reçoit l’événement avec `account` défini sur le compte qui a installé votre application, et les endpoints de webhook de votre propre compte reçoivent un événement distinct sans `account`. Une plateforme d’intégration reçoit l’événement sur les endpoints de webhook de son propre compte.

Pour les versions d’API antérieures au 30 septembre 2026, les événements d’installation sont nommés `app.install.created`, `app.install.updated` et `app.install.deleted`. Abonnez chaque endpoint de webhook aux noms correspondant à sa version d’API, ou à tous les événements. Un endpoint abonné aux noms d’une autre version d’API ne reçoit pas les événements d’installation.

Les événements `apps.install.created` et `apps.install.updated` renvoient des données sous la forme d’une ressource d’API App Install. L’événement `apps.install.deleted` ne renvoie que les champs `id`, `object` et `deleted` de l’installation. Pour le faire correspondre à une installation, utilisez l’`id` de l’installation, ou l’`account` de l’événement sur votre endpoint de webhook Connect. Pour tous les champs, consultez l’[objet App Install](https://docs.stripe.com/api/apps/installs/object.md).

### Définitions des ressources de l’API App Install.

La ressource d’installation de l’application comprend les champs suivants :

| Champ | Description |
| --- | --- |
| `id` | Un identifiant unique associé à l’installation de l’application. |
| `account` | L’identifiant du compte Stripe qui a installé l’application. |
| `app` | L’identifiant unique associé à l’application. |
| `permissions_granted` | L’ensemble des autorisations que le compte a accordées pour votre application. |
| `content_security_policy_granted` | L’ensemble des URL que l’utilisateur a autorisé votre application à communiquer avec dans le Dashboard Stripe. |
| `channel` | Le canal de distribution de votre application. Par exemple, « public » ou « test ». |
| `created` | L’horodatage de l’installation de l’application. |
| `livemode` | Vrai si l’application a été installée en mode production. |
| `status` | Le statut de l’installation. Par exemple, « installed » ou « install_failed ». |

**Exemple :**

```json
{
  "object": {
    "object": "apps.install",
    "id": "appinst_1234",
    "account": "acct_1234",
    "app": "app_1234",
    "permissions_granted": [],
    "content_security_policy_granted": {
      "connect_src": [],
      "image_src": []
    },
    "channel": "public",
    "created": 123,
    "livemode": true,
    "status": "installed"
  }
}
```

## Tester des webhooks localement

Vous pouvez tester des webhooks en local pour :

- Une application qui n’est accessible qu’aux utilisateurs de votre compte et qui écoute les événements sur votre propre compte
- Une application disponible sur le Stripe App Marketplace et qui écoute les événements sur les comptes qui ont installé votre application

Pour tester des webhooks en local :

1. [Installer l’interface de ligne de commande Stripe](https://docs.stripe.com/cli.md).

2. Authentifiez votre compte :

   ```bash
   stripe login
   ```

3. Ouvrez deux fenêtres de terminal :

   - Dans une fenêtre de terminal, [configurez le transfert d’événements](https://docs.stripe.com/webhooks.md#local-listener) :

     #### Publication sur l'App Marketplace

     ```bash
     stripe listen --forward-connect-to localhost:{{PORT}}/webhook
     ```

     #### Privé pour votre compte uniquement

     ```bash
       stripe listen --forward-to localhost:{{PORT}}/webhook
     ```

   - Dans l’autre fenêtre de terminal, [déclenchez des événements pour tester votre intégration des webhooks](https://docs.stripe.com/webhooks.md#trigger-test-events) :

     #### Publication sur l'App Marketplace

     ```bash
     stripe trigger --stripe-account {{EVENT_NAME}}
     ```

     #### Privé pour votre compte uniquement

     ```bash
       stripe trigger {{EVENT_NAME}}
     ```

Pour plus d’informations, consultez notre documentation relative au [test d’un point de terminaison de webhook](https://docs.stripe.com/webhooks.md#local-listener).

## See also

- [Logique côté serveur](https://docs.stripe.com/stripe-apps/build-backend.md)
- [Documentation relatives aux autorisations](https://docs.stripe.com/stripe-apps/reference/permissions.md)
- [Types d’authentification de l’API](https://docs.stripe.com/stripe-apps/api-authentication.md)
- [destinations d’événements](https://docs.stripe.com/events/how-events-work.md#event-destinations)
- [Webhooks](https://docs.stripe.com/webhooks.md)