Stripe uses webhooks to notify your application any time an event happens on your account. Set up webhooks for events that Stripe doesn’t already notify you of, like when a customer’s bank confirms a PaymentIntent, a customer disputes a charge, or your recurring subscription succeeds.

A webhook endpoint is like a phone number that Stripe calls when certain things happen in your Stripe account. Stripe creates an Event object for each occurrence in your Stripe account that’s worth notifying you about, like the creation of a new customer in your Stripe account, or a payout to your bank account. Each event contains data explaining what happened.

When you create a webhook handler, it listens for specific events, then takes action whenever those events get sent to the endpoint. Technically, a webhook handler is just a script in a server-side language, like Ruby or PHP, that handles any events you specify in the Dashboard. See all event types.

Webhooks can also be used to provide state and API responses to services or systems that use Stripe data for things like replication, analytics, or alerting.

When to use webhooks

Webhooks are necessary for behind-the-scenes transactions like the Payment Intents API with automatic confirmation or most payment methods using Sources. In APIs like these, Stripe needs to notify your integration about changes to the status of the object so that you can act on them.

Some Stripe requests (e.g., creating charges or refunds) generate results that Stripe reports synchronously to your code. These integrations don’t require your verification, but the events allow you to share information with other systems. You can also use webhooks in these synchronous integrations to automate business tasks:

• Update a customer’s membership record in your database when a subscription payment succeeds
• Email a customer when a subscription payment fails
• Examine the Dashboard if you see that a dispute was filed
• Make adjustments to an invoice when it’s created (but before it’s been paid)
• Log an accounting entry when a transfer is paid

Quickstart

The Stripe CLI provides a quick way for you to see events being created on your account. With the CLI you can get a look behind the scenes at all the events that are created when specific actions happen on your account:

stripe listen
Ready! Your webhook signing secret is {{SIGNING_SECRET}} (^C to quit)

In a new tab, run:

stripe trigger payment_intent.created

Going back to the tab with listen running, you should see the event coming in:

stripe listen
Ready! Your webhook signing secret is {{SIGNING_SECRET}} (^C to quit)
2019-09-24 11:01:22  Received: payment_intent.created [evt_1FMIKEByst5pquEtW2TQHNP6]

Next steps

• Building a webhook endpoint
• Configuring the endpoint
• Checking webhook signatures
• Best practices for using webhooks