Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
Versioning
Changelog
Upgrade your API version
Upgrade your SDK version
Developer tools
SDKs
API
Testing
Workbench
Event Destinations
Workflows
Stripe CLI
Stripe Shell
Developers Dashboard
Agent toolkit
Stripe health alertsBuild with LLMsStripe for Visual Studio CodeFile uploads
Security
Security
Extend Stripe
Stripe Apps
    Overview
    Get started
    Create an app
    How Stripe Apps work
    Sample apps
    Build an app
    Store secrets
    API authentication methods
    Authorization flows
    Server-side logic
    Listen to events
    Handle different modes
    Enable sandbox support
    App settings page
    Build a UI
    Onboarding
    Distribute your app
    Distribution options
    Upload your app
    Versions and releases
    Test your app
    Publish your app
    Promote your app
    Add deep links
    Create install links
    Assign roles in UI extensions
    Post-install actions
    App analytics
    Embedded components for Apps
    Embed third-party Stripe Apps
    Migrating to Stripe Apps
    Migrate or build an extension
    Migrate a plugin to Stripe Apps or Stripe Connect
    Reference
    App manifest
    CLI
    Extension SDK
    Permissions
    Viewports
    Design patterns
    Components
Stripe Connectors
Partners
Partner ecosystem
Partner certification
HomeDeveloper toolsStripe Apps

Listen for events

Listen for events on your installed users accounts

Copy page

Apps can use Webhooks 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.
  2. Register a webhook endpoint in the Stripe Dashboard, and select Listen to events on Connected accounts.
  3. Recommended Register a test webhook endpoint in the Stripe Dashboard. You can install apps in live mode, test mode, or a sandbox. We also recommend setting up a test endpoint to handle test events.
  4. Add the required permissions to your app by running stripe apps grant permission for each one.
    Command Line
    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.

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

Command Line
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:

stripe-app.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 in your app’s back end.
  2. Register a webhook endpoint 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 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, Stripe Apps also supports the following events:

Merchant actionResulting webhook event sent to the app’s backend
Connect or install your appaccount.application.authorized
Disconnect or uninstall your appaccount.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.

  2. Authenticate your account:

    Command Line
    stripe login
  3. Open two terminal windows:

    • In one terminal window, Set up event forwarding:

      Command Line
      stripe listen --forward-connect-to localhost:{{PORT}}/webhook
    • In the other terminal window, Trigger events to test your webhooks integration:

      Command Line
      stripe trigger --stripe-account {{EVENT_NAME}}

For more information, see our docs on testing a webhook endpoint.

See also

  • Server-side logic
  • Permissions reference
  • API Authentication Types
  • Event destinations
  • Webhooks
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc