# Listen for events

Listen for events on your installed users accounts

Apps can use [Webhooks](https://docs.stripe.com/webhooks.md) to get alerts about events happening on their users’ accounts. This helps app developers keep information in sync or trigger actions within their app when something changes.

## Get started 

1. [Handle webhook events in your app’s back end](https://docs.stripe.com/webhooks.md#webhook-endpoint-def).
1. [Register a webhook endpoint](https://docs.stripe.com/webhooks.md#webhooks-summary) in the Stripe Dashboard, and select **Listen to events on Connected accounts**.
1. (Recommended) Register a test webhook endpoint in the Stripe Dashboard. You can install apps in live mode, [test mode](https://docs.stripe.com/stripe-apps/build-backend.md#event-behavior-depends-on-install-mode), or a *sandbox* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes). We also recommend setting up a test endpoint to handle test events.
1. Add the required permissions to your app by running `stripe apps grant permission` for each one.
   ```bash
   stripe apps grant permission "PERMISSION_NAME" "EXPLANATION"
   ```
Replace:
   - `PERMISSION_NAME` with the permission name.
   - `EXPLANATION` with an explanation for enabling access. Users see this explanation when they install your app.

You must add the `event_read` permission, plus any permissions associated with the specific events you want to handle. For information about which permissions a particular event requires, see [Event permissions](https://docs.stripe.com/stripe-apps/reference/permissions.md#event-permissions).

For example, if you want to handle the `payment_intent.succeeded` and `setup_intent.succeeded` events, run the following commands:

```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"
```

After you run those commands, your app manifest file might look like this:

```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"
    }
  ]
}
```

## Listen for events on your account 

To receive events for an app that’s private to users on your account only:

1. Handle [webhook events](https://docs.stripe.com/webhooks.md#webhook-endpoint-def) in your app’s back end.
1. [Register a webhook endpoint](https://docs.stripe.com/webhooks.md#webhooks-summary) in the Stripe Dashboard.

## Receive event notifications about your app 

Listen for events (such as user installs or uninstalls) on your Stripe app using incoming *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) so your integration can automatically trigger reactions in your back end such as:

- Creating user accounts
- Updating permissions
- Disabling a user’s account and removing data

In addition to the [types of events Stripe supports](https://docs.stripe.com/api/events/types.md), Stripe Apps also supports the following events:

| Merchant action                  | Resulting webhook event sent to the app’s backend                                                                            |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Connect or install your app      | [account.application.authorized](https://docs.stripe.com/api/events/types.md#event_types-account.application.authorized)     |
| Disconnect or uninstall your app | [account.application.deauthorized](https://docs.stripe.com/api/events/types.md#event_types-account.application.deauthorized) |

## Test webhooks locally 

You can test webhooks locally for:

- An app that’s only available to all users on your account and listens to events on your own account
- An app that’s available on the Stripe App Marketplace and listens to events on accounts that have installed your app

To test webhooks locally:

1. [Install the Stripe CLI](https://docs.stripe.com/stripe-cli.md).

1. Authenticate your account:

   ```bash
   stripe login
   ```

1. Open two terminal windows:

   - In one terminal window, [Set up event forwarding](https://docs.stripe.com/webhooks.md#local-listener):

     #### Public listing on App Marketplace

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

     #### Private to your account only

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

   - In the other terminal window, [Trigger events to test your webhooks integration](https://docs.stripe.com/webhooks.md#trigger-test-events):

     #### Public listing on App Marketplace

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

     #### Private to your account only

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

For more information, see our docs on [testing a webhook endpoint](https://docs.stripe.com/webhooks.md#local-listener).

## See also

- [Server-side logic](https://docs.stripe.com/stripe-apps/build-backend.md)
- [Permissions reference](https://docs.stripe.com/stripe-apps/reference/permissions.md)
- [API Authentication Types](https://docs.stripe.com/stripe-apps/api-authentication.md)
- [Event destinations](https://docs.stripe.com/event-destinations.md)
- [Webhooks](https://docs.stripe.com/webhooks.md)