Receive event notifications with webhooks
Stripe uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like when a customer’s bank confirms a payment, a customer disputes a charge, or a recurring payment succeeds.
Begin using webhooks with your Stripe integration in just three steps:
- Create a webhook endpoint on your server.
- Use the Stripe CLI to test that your endpoint works.
- Register the endpoint with Stripe to go live.
Not all Stripe integrations require webhooks. Keep reading to learn more about what webhooks are and when you should use them.
What are webhooks
Webhooks refers to a combination of elements that collectively create a notification and reaction system within a larger integration.
Metaphorically, webhooks are like a phone number that Stripe calls to notify you of activity in your Stripe account. The activity could be the creation of a new customer or the payout of funds to your bank account. The webhook endpoint is the person answering that call who takes actions based upon the specific information it receives.
Non-metaphorically, the webhook endpoint is just more code on your server, which could be written in Ruby, PHP, Node.js, or whatever. The webhook endpoint has an associated URL (e.g., https://example.com/webhooks). The Stripe notifications are Event objects. This Event object contains all the relevant information about what just happened, including the type of event and the data associated with that event. The webhook endpoint uses the event details to take any required actions, such as indicating that an order should be fulfilled.
When to use webhooks
Many events that occur within a Stripe account have synchronous results–immediate and direct–to an executed request. For example, a successful request to create a customer immediately returns a Customer object. Such requests don’t require webhooks, as the key information is already available.
Other events that occur within a Stripe account are asynchronous: happening at a later time and not directly in response to your code’s execution. Most commonly these involve:
- The Payment Intents API
- Notifications of payouts
- Subscriptions
With these and similar APIs, Stripe needs to notify your integration about changes to the status of an object so your integration can take subsequent steps.
The specific actions your webhook endpoint may take differs based upon the event. Some examples include:
- Updating a customer’s membership record in your database when a subscription payment succeeds
- Making adjustments to an invoice when it’s created (but before it’s been paid)
- Logging an accounting entry when a transfer is paid
- Indicating that an order can be fulfilled (i.e., boxed and shipped)
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.