Skip to content
Sign in
An image of the Stripe logo
/
Create account
Sign in
Home
Payments
Finance automation
Banking as a service
Developer tools
No-code
All products
Home
Payments
Finance automation
Home
Payments
Finance automation
Banking as a service
Developer tools
Overview
Get started
About Stripe payments
Start an integration
Payment Links
Checkout
Web Elements
Mobile Elements
Payment scenarios
During the payment
After the payment
Add payment methods
More payment scenarios
Faster checkout with Link
Other Stripe products
Connect
    Overview
    Get started
    Collect payments then pay out
    Enable other businesses to accept payments directly
    Pay out money
    Explore Connect
    Onboard your accounts
    Choose your account type
    Standard
    Express
    Custom
    Update accounts
    Service agreement types
    Payment methods
    Account capabilities
    Handle verification with the API
    Additional Verifications
    Update verified info
    Connect embedded components
    Quickstart
    Quickstart (beta)
    Get started with Connect embedded components
    Customize Connect embedded components
    Accept payments
    Create a charge
    Create a payments page
    Create payment links with Connect
    Connect integration guide
    Dynamic payment methods
    Set statement descriptors
    Connect platforms using the Payment Methods API
    Create subscriptions
    Create invoices
    Debit Express and Custom connected accounts
    Pay out
    Set bank and debit card payouts
    Bank accounts and debit cards
    Manage payout schedule
    Manual payouts
    Payout reversals
    Instant Payouts
    Cross-border payouts
    Crypto payouts
    Manage funds
    Add money to your platform balance
    Account balance
    Handle multiple currencies
    Manage accounts
    Best practices
    Listen for updates
    Dashboard account management
    Understanding risk offerings
    Platform controls for Standard accounts
    Make API calls for connected accounts
    Set MCCs
    Testing
    Payment Method Configurations API
    Migrate to Payment Method Configurations API
    Multiple payment method configurations
    Manage tax forms
    Overview
    Get started with tax reporting
    1099 Tax Support and Communication Guide
    Tax form settings
    Calculation methods
    Identity information on tax forms
    File tax forms
    File tax forms with states
    Identify forms with missing information
    Update tax forms
    Deliver tax forms
    Deliver tax forms with Stripe Express
    Correct tax forms
    Split tax forms
    Tax year changeover
    What's new for tax year 2023
Terminal
Radar
Financial Connections
Crypto
Identity
Climate
Resources
About the APIs
Implementation guides
Regulation support
Testing
Connect
·
HomePaymentsConnect

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.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.

Webhook settings in the Stripe 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":
"{{EVENT_ID}}"
, "livemode": true, "object": "event", "type": "customer.created", "account":
"{{CONNECTED_ACCOUNT_ID}}"
, "pending_webhooks": 2, "created": 1349654313, "data": {...} }

There are several events related to accounts that Stripe recommends listening for:

Eventdata.object typeDescription
account.application.deauthorizedapplicationOccurs 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.updatedAn external account, such as card or bank_accountOccurs 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.updatedaccountAllows you to monitor changes to connected account requirements and status changes. Available for Standard, Express, and Custom accounts.
balance.availablebalanceOccurs 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.succeededpayment_intentOccurs when a payment intent results in a successful charge. Available for all payments, including destination and direct charges.
payout.failedpayoutOccurs 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.updatedpersonIf you use the Persons API, allows you to monitor changes to requirements and status changes for individuals. Available for Express and Custom accounts.
server.rb
# Using Sinatra. require 'sinatra' require 'stripe' set :port, 4242 # Set your secret key. Remember to switch to your live secret key in production. # See your keys here: https://dashboard.stripe.com/apikeys Stripe.api_key =
'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
# If you are testing your webhook locally with the Stripe CLI you # can find the endpoint's secret by running `stripe listen` # Otherwise, find your endpoint's secret in your webhook settings in # the Developer Dashboard endpoint_secret = 'whsec_...' post '/webhook' do payload = request.body.read sig_header = request.env['HTTP_STRIPE_SIGNATURE'] event = nil # Verify webhook signature and extract the event. # See https://stripe.com/docs/webhooks#verify-events for more information. begin event = Stripe::Webhook.construct_event( payload, sig_header, endpoint_secret ) rescue JSON::ParserError => e # Invalid payload. status 400 return rescue Stripe::SignatureVerificationError => e # Invalid Signature. status 400 return end if event['type'] == 'account.application.deauthorized' application = event['data']['object'] connected_account_id = event['account'] handle_deauthorization(connected_account_id, application) end status 200 end def handle_deauthorization(connected_account_id, application) # Clean up account state. puts 'Connected account ID: ' + connected_account_id puts application.to_s end

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.

  1. If you haven’t already, install the Stripe CLI on your machine.

  2. Log in to your Stripe account and set up the CLI by running stripe login on the command line.

  3. 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 running stripe trigger {{EVENT_NAME}} in another.

Note

For Connect webhooks, use --forward-connect-to with stripe listen and --stripe-account with stripe trigger.

See also

  • Webhook documentation
  • Event object reference
Was this page helpful?
Need help? Contact Support.
Watch our developer tutorials.
Check out our product changelog.
Questions? Contact Sales.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
Stripe Shell
Test mode
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Log in to your Stripe account and press Control + Backtick (`) on your keyboard to start managing your Stripe resources in test mode. - View supported Stripe commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g., )
The Stripe Shell is best experienced on desktop.
$