Connect webhooks
Learn how to use webhooks with Connect to be notified of Stripe activity.
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.
event for any connected account and direct charges.updated
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, only test webhooks are sent to your development webhook URLs, but both live and test webhooks are sent to your production webhook URLs. This is because you can perform both live and test transactions under a production application. For this reason, we recommend that you check the livemode
value when receiving an event webhook to know what action, if any, users should take.
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 | Occurs when a connected account disconnects from your platform. You can use it to trigger cleanup on your server. Available for connected accounts with access to the Stripe Dashboard, which includes Standard accounts. |
account. | An external account, such as card or bank_ | Occurs when a bank account or debit card attached to a connected account is updated, which can impact payouts. Available for connected accounts that your platform controls, which includes Custom and Express accounts, and Standard accounts with platform controls enabled. |
account. | account | Allows you to monitor changes to connected account requirements and status changes. Available for all connected accounts. |
balance. | 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_ | payment_ | Occurs when a payment intent results in a successful charge. Available for all payments, including destination and direct charges. |
payout. | 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. | person | If you use the Persons API, allows you to monitor changes to requirements and status changes for individuals. Available for connected accounts that your platform controls, which includes Custom and Express accounts, and Standard accounts with platform controls enabled. |
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_
in another.NAME}}
Note
For Connect webhooks, use –forward-connect-to with stripe listen
and –stripe-account with stripe trigger
.