Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
No-code
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Online payments
Products and prices
Invoicing
Subscriptions
Quotes
In-person payments
Multiparty payments
After the payment
    Overview
    Payouts
    Declines
    Email receipts
    Refund and cancel payments
    Handle webhook events
Add payment methods
Payment Links
Stripe Checkout
Stripe Elements
About the APIs
Regulation support
Implementation guides
Testing
HomePaymentsAfter the payment

Triggering actions with webhooks

How to use webhooks to respond to offline payment events.

A webhook is an HTTP endpoint that receives events from Stripe.

Webhooks allow you to be notified about payment events that happen in the real world outside of your payment flow such as:

  • Successful payments (payment_intent.succeeded)
  • Disputed payments (charge.dispute.created)
  • Available balance in your Stripe account (balance.available)

While the Dashboard is great for one-off actions like refunding a payment or updating a customer’s information, webhooks are essential for scaling your payments integration by helping you process large volumes of business-critical events.

Build your own webhook

You can build a webhook handler on your own server to manage all your offline payment flows. Start by exposing an endpoint that can receive requests from Stripe and use the CLI to locally test your integration. Each request from Stripe contains an Event object with a reference to the object on Stripe that was modified.

Create a webhook endpoint

Add a new endpoint in your application. You can act on certain events by checking the type field of the event object sent in the request body. For now, let’s print to standard output to make sure our webhook is working.

Start your server after adding the new endpoint.

# 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'
require 'stripe' require 'sinatra' require 'json' # Using the Sinatra framework set :port, 4242 post '/webhook' do payload = request.body.read event = nil begin event = Stripe::Event.construct_from( JSON.parse(payload, symbolize_names: true) ) rescue JSON::ParserError => e # Invalid payload status 400 return end # Handle the event case event.type when 'payment_intent.succeeded' payment_intent = event.data.object # contains a Stripe::PaymentIntent puts 'PaymentIntent was successful!' when 'payment_method.attached' payment_method = event.data.object # contains a Stripe::PaymentMethod puts 'PaymentMethod was attached to a Customer!' # ... handle other event types else puts "Unhandled event type: #{event.type}" end status 200 end

Install and set up the Stripe CLI

Command Line
# Install Homebrew to run this command: https://brew.sh/ brew install stripe/stripe-cli/stripe # Connect the CLI to your dashboard stripe login

For additional install options, see Get started with the Stripe CLI.

Use the --project-name flag when you log in to configure different projects. You can then run commands with --project-name to use that configuration.

After you have the Stripe CLI installed, run stripe login in the command line to generate a pairing code to link to your Stripe account. Press Enter to launch your browser and log in to your Stripe account to allow access. The generated API key is valid for 90 days. You can modify or delete the key under API Keys in the Dashboard.

Command Line
stripe login Your pairing code is: humour-nifty-finer-magic Press Enter to open up the browser (^C to quit)

If you want to use an existing API key, use the --api-key flag:

Command Line
stripe login --api-key
sk_test_4eC39HqLyjWDarjtT1zdp7dc
Your pairing code is: humour-nifty-finer-magic Press Enter to open up the browser (^C to quit)

Test your webhook locally

Use the CLI to forward events to your local webhook endpoint using the listen command.

Assuming your application is running on port 4242, run:

Command Line
stripe listen --forward-to http://localhost:4242/webhook

In a different terminal tab, use the trigger CLI command to trigger a mock webhook event.

Command Line
stripe trigger payment_intent.succeeded

You should see the follow event in your listen tab:

Command Line
[200 POST] OK payment_intent.succeeded

You should also see “PaymentIntent was successful!” printed in the terminal tab your server is running.

OptionalCheck webhook signature

Deploy your webhook endpoint

When you’re ready to deploy your webhook endpoint to production there are a couple things you need to do:

  1. Use your live mode API keys and not your test mode keys.

  2. Configure your webhook endpoint in the Stripe Dashboard or with the API.

To configure your endpoint in the Dashboard, go to your webhook settings.

Click “Add endpoint” and enter the URL of your endpoint, the Stripe API version, and the specific events you want Stripe to send.

Replace the webhook endpoint secret in your application with the new secret shown in the Dashboard view of your endpoint.

That’s it! Your application is ready to accept live events. For more information on configuring your webhook endpoint, the Webhook Endpoint API, and testing in test mode see our Development guide.

Was this page helpful?
Questions? Contact us.
Watch our developer tutorials.
Check out our product changelog.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Build your own webhook
Create a webhook endpoint
Install and set up the Stripe CLI
Test your webhook locally
Check webhook signature
Deploy your webhook endpoint
Stripe Shell
Test mode
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Login 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.
$