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

A Connect platform uses two 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. We send all events on the connected account (including account updates and direct charges) to the Connect webhooks.

When you create a Connect webhook, you must configure it to receive Connect webhook events. When creating it in the Dashboard, for Listen to, select Events on Connected accounts. When creating it using the API, set the connect parameter to true.

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.

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

# 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_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

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.