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

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.

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:

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