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

Webhooks for Connect users listen for events in different scopes, depending on the source of the event:

• Your account: Most events triggered by resources that exist in your account. That includes most requests made using your API keys and without authenticating as another Stripe account, such as:
  • v2.core.account.* events for v2 Accounts in your account
  • Events for Customers in your account
  • Events for direct charges on your account
  • Events for indirect charges on your account for your connected accounts
• Connected accounts: Events triggered by resources that exist in connected accounts and some resources that exist in your account, such as:
  • v2.core.account.* events for v2 Accounts representing customers and recipients of your connected accounts
  • v1 account.updated events for both v1 and v2 Accounts representing customers and recipients of your connected accounts
  • Direct charges for customers of your connected accounts

When you create a webhook in Workbench, assign the scope by setting Events from to Your account or Connected accounts. When you create a webhook using the API, assign the scope by setting the connect parameter to false (for Your account) or true (for Connected accounts).

For Connect webhooks, your development webhook URLs receive only test webhooks, but your production webhook URLs receive both live and test webhooks. This is because you can perform both live and test transactions under a production application. We recommend that you check the livemode value when receiving an event webhook to determine whether users need to take action.

You must define separate webhook endpoints for your sandbox accounts to receive events for those accounts.

Each event for a connected account contains a top-level account property that identifies the connected account. Because the connected account owns the object that triggered the event, you must make API requests for that object as the connected account.

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

The following table describes some of the most common and important events related to connected accounts:

# Using Sinatra.
require 'sinatra'
require 'stripe'

set :port, 4242

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2')

# If you're 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

Test webhooks locally

To test event 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 by running stripe listen, depending on the scope of the event:

   • Connected accounts: stripe listen --forward-connect-to localhost:{{PORT}}/{{CONNECT_WEBHOOK_ENDPOINT}}
   • Your account: stripe listen --forward-to localhost:{{PORT}}/{{WEBHOOK_ENDPOINT}}

4. In another terminal window, trigger a simulated event by running stripe trigger, depending on the scope of the event:

   • Connected accounts: stripe trigger --stripe-account {{CONNECTED_ACCOUNT_ID}} {{EVENT_NAME}}
   • Your account: stripe trigger {{EVENT_NAME}}