Listen for events
Listen for events on your installed users accounts
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
- Handle webhook events in your app’s back end.
- Register a webhook endpoint in the Stripe Dashboard, and select Listen to events on Connected accounts.
- Register a test mode webhook endpoint in the Stripe Dashboard. Apps can be installed in both live and test mode. We also recommend setting up a test mode endpoint to handle test mode events. Recommended
- Add the required permissions to your app by running
stripe apps grant permission
for each one.Replace:Command Linestripe apps grant permission "PERMISSION_NAME" "EXPLANATION"
PERMISSION_
with the permission name.NAME EXPLANATION
with an explanation for enabling access. Users see this explanation when they install your app.
You must add the event_
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_
and setup_
events, run the following commands:
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:
{ "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:
- Handle webhook events in your app’s back end.
- 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 action | Resulting webhook event sent to the app’s backend |
---|---|
Connect or install your app | account.application.authorized |
Disconnect or uninstall your app | 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:
Authenticate your account:
Command Linestripe login
Open two terminal windows:
In one terminal window, Set up event forwarding:
In the other terminal window, Trigger events to test your webhooks integration:
For more information, see our docs on testing a webhook endpoint.