# 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).
2. [Register a webhook endpoint](https://docs.stripe.com/webhooks.md) in the Stripe Dashboard, and select **Listen to events on Connected accounts**.
3. (Recommended) Register webhook endpoints for every environment where users install your app: live mode, the test mode sandbox, or a general sandbox. For public apps installed in a general sandbox, [configure webhook endpoints in your app’s managed sandbox](https://docs.stripe.com/stripe-apps/enable-sandbox-support.md#configure-webhook-events). For private apps, register webhook endpoints in the same environment where the app is installed. For public apps installed in live mode or the test mode sandbox, follow the [webhook routing rules](https://docs.stripe.com/stripe-apps/handling-modes.md).
4. 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 installation events, `livemode=false` indicates a sandbox installation. It doesn’t identify the sandbox type.

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.
2. [Register a webhook endpoint](https://docs.stripe.com/webhooks.md) 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 |
| --- | --- |
| Install your app | [apps.install.created](https://docs.stripe.com/api/events/types.md#event_types-apps.install.created) |
| Update or reauthorize your app | [apps.install.updated](https://docs.stripe.com/api/events/types.md#event_types-apps.install.updated) |
| Uninstall your app | [apps.install.deleted](https://docs.stripe.com/api/events/types.md#event_types-apps.install.deleted) |

Stripe also sends [account.application.authorized](https://docs.stripe.com/api/events/types.md#event_types-account.application.authorized) when an account connects or installs your app, and [account.application.deauthorized](https://docs.stripe.com/api/events/types.md#event_types-account.application.deauthorized) when an account disconnects or uninstalls it.

Stripe sends each install event to the app developer, to the account that installed the app, and to the embedding platform that created the install, if any. For an install on another account, your Connect webhook endpoint receives the event with `account` set to the account that installed your app, and your account’s own webhook endpoints receive a separate event without `account`. An embedding platform receives the event on its own account’s webhook endpoints.

On API versions before 2026-09-30, the install events are named `app.install.created`, `app.install.updated`, and `app.install.deleted`. Subscribe each webhook endpoint to the names for its API version, or to all events. An endpoint that’s subscribed to the names for a different API version doesn’t receive the install events.

The `apps.install.created` and `apps.install.updated` events return data as an App Install API resource. The `apps.install.deleted` event returns only the install’s `id`, `object`, and `deleted` fields. To match it to an install, use the install `id`, or the event’s `account` on your Connect webhook endpoint. For all fields, see the [App Install object](https://docs.stripe.com/api/apps/installs/object.md).

### App Install API resource definitions

The App Install resource includes the following fields:

| Field | Description |
| --- | --- |
| `id` | A unique ID associated with the app install. |
| `account` | The ID of the Stripe account that installed the app. |
| `app` | The unique ID associated with the app. |
| `permissions_granted` | The set of permissions the account authorized for your app. |
| `content_security_policy_granted` | The set of URLs the user authorized your app to communicate with in the Stripe Dashboard. |
| `channel` | The distribution channel for your app. For example, “public” or “testing”. |
| `created` | The timestamp of when the app was installed. |
| `livemode` | True if the app was installed into live mode. |
| `status` | The status of the install. For example, “installed” or “install_failed”. |

**Example:**

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

## 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/cli.md).

2. Authenticate your account:

   ```bash
   stripe login
   ```

3. 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/events/how-events-work.md#event-destinations)
- [Webhooks](https://docs.stripe.com/webhooks.md)