Handle payment events 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 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 )

You can use the Dashboard for one-off actions like refunding a payment or updating a customer’s information, while webhooks help you scale your payments integration and 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. Then you can print to standard output to make sure your webhook is working.

Start your server after adding the new endpoint.

Select a language

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

# 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')

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

Install the Stripe CLI with npm:

Command Line

npm install -g @stripe/cli@latest

After installation, log in to your Stripe account:

Command Line

stripe login

After you install the CLI, you can also install agent tooling, or set up autocompletion.

Note

For more installation options for Windows, macOS, Linux, and Docker, see the Stripe CLI readme on GitHub.

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

The following event appears in your listen tab:

Command Line

[200 POST] OK payment_intent.succeeded

“PaymentIntent was successful!” appears in the terminal tab your server is running.

Optional Check webhook signature

Deploy your webhook endpoint

When you’re ready to deploy your webhook endpoint to production you need to do the following:

1. Use your live mode API keys and not your test keys.
2. Configure your webhook endpoint in Workbench or with the API.
3. To configure your endpoint in Workbench, go to the Webhooks tab .
4. Click Add destination and enter the Stripe API version and the specific events you want Stripe to send. Click Continue and select Webhook endpoint from the list of available destination types. Click Continue and enter the URL of your endpoint, optional name, and optional description. Click Create destination .
5. Replace the webhook endpoint secret in your application with the new secret shown in the destination details view in Workbench for your endpoint.

Your application is now ready to accept live events. For more information on configuring your webhook endpoint, see the Webhook Endpoint API. For testing in a sandbox, see our Development guide.