Connect webhooks

    Learn how to use webhooks with Connect to be notified of Stripe activity.

    All Connect integrations should establish a webhook endpoint to listen for Connect events.

    • If Standard accounts connect to your platform you should set up a Connect webhook endpoint to listen for account.application.deauthorized events. These events occur when a user disconnects from your account and can be used to trigger required cleanup on your server.
    • If your integration uses Express or Custom accounts there are several events types your Connect webhook endpoint should listen for:
      • account.updated events will allow you to monitor changes to connected account requirements and status changes.
      • person.updated events will, if you use the Persons API, allow you to monitor changes to requirements and status changes for individuals.
      • account.external_account.updated events occur when a bank account or debit card attached to a connected account is updated, which can impact payouts.
      • payout.failed events occur 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.

    The events listed above are the ones we recommend all Connect integrations listen for, but there are many other event types you may be interested in.

    Note that there are a few types of webhooks:

    • Account webhooks are for activity on your own account (e.g., most requests made using your API keys and without authenticating as another Stripe account).
    • Connect webhooks are for activity on any connected account. This includes the important account.updated event for any connected accounts.
    • Person webhooks are for activity on any person associated with a connected account. This includes the person.updated event which provides important verification information. You only receive this webhook if you use the Persons API.

    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.

    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.

    In addition to the documented response properties in the event object reference, each event for a connected account will also contain a top-level account property. It identifies the user for whom the webhook is being sent.

    { "id": "evt_m07iNeCac3Zx6N", "livemode": true, "object": "event", "type": "customer.created", "account": "acct_L2QLg3bj0lAmZW", "pending_webhooks": 2, "created": 1349654313, "data": {...} }

    For more information about webhooks, see the webhook documentation or event object reference.

    Was this page helpful?

    Feedback about this page?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    On this page