Connect webhooks
Stripe uses webhooks to notify your application when an event happens in your account. All Connect integrations should establish a webhook endpoint to listen for Connect events.
Connect webhooks
There are a few types of webhooks:
- Account webhooks are for activity on your own account (for example, most requests made using your API keys and without authenticating as another Stripe account). This includes all types of charges, except those made directly on a connected account.
- Connect webhooks are for activity on any connected account. All events on the connected account are sent to the Connect webhooks. This includes the important
account.updated
event for any connected account and direct charges.
When creating your webhook, ensure it is correctly configured to receive Connect webhook events. You can do this with the API by setting the connect parameter to true
when creating the webhook endpoint, or through the Dashboard.

For Connect webhooks, it’s important to note that while only test webhooks will be sent to your development webhook URLs, both live and test webhooks will be sent to your production webhook URLs. This is due to the fact that you can perform both live and test transactions under a production application. For this reason, we recommend you check the livemode
value when receiving an event webhook to know what action, if any, should be taken.
As we state in the event object reference, each event for a connected account also contains a top-level account
property. It identifies the account that the webhook is sent to and the data[object]
it belongs to. Because these objects belong to other accounts, you must make the API requests as the corresponding connected account to access them.
{ "id":
, "livemode": true, "object": "event", "type": "customer.created", "account":"{{EVENT_ID}}", "pending_webhooks": 2, "created": 1349654313, "data": {...} }"{{CONNECTED_ACCOUNT_ID}}"
There are several events related to accounts that Stripe recommends listening for:
Event | data.object type | Description |
---|---|---|
account.application.deauthorized | application | Occurs when a user disconnects from your account and can be used to trigger required cleanup on your server. Available for Standard accounts. |
account.external_account.updated | An external account, such as card or bank_account | Occurs when a bank account or debit card attached to a connected account is updated, which can impact payouts. Available for Express and Custom accounts. |
account.updated | account | Allows you to monitor changes to connected account requirements and status changes. Available for Standard, Express, and Custom accounts. |
balance.available | balance | Occurs when your Stripe balance has been updated (for example, when funds you’ve added from your bank account are available for transfer to your connected account). |
payment_intent.succeeded | payment_intent | Occurs when a payment intent results in a successful charge. Available for all payments, including destination and direct charges. |
payout.failed | payout | Occurs when a payout fails. When a payout fails, the external account involved will be disabled, and no automatic or manual payouts can go through until the external account is updated. |
person.updated | person | If you use the Persons API, allows you to monitor changes to requirements and status changes for individuals. Available for Express and Custom accounts. |
The events listed above are the ones we typically recommend Connect integrations listen for, but there are many other event types you may be interested in.
Test webhooks locally
You can test webhooks locally with the Stripe CLI.
If you haven’t already, install the Stripe CLI on your machine.
Log in to your Stripe account and set up the CLI by running
stripe login
on the command line.Allow your local host to receive a simulated event on your connected account by running
stripe listen --forward-to localhost:{PORT}/webhook
in one terminal window, and runningstripe trigger {{EVENT_NAME}}
in another.
Note
For Connect webhooks, use --forward-connect-to
with stripe listen
and --stripe-account
with stripe trigger
.