What are Stripe webhooks?

When an asynchronous event happens in your Stripe account; for example, a customer’s bank confirms a payment, a recurring payment succeeds, or a customer disputes a charge; Stripe uses webhooks to notify your application.

What are webhooks?

Webhooks (also called a web callback or HTTP push API) enable Stripe to send notifications to your website immediately when certain events occur.

A webhook is similar to a phone number that Stripe calls in order to let you know about a given activity in your account. There can be different activities such as the creation of a new customer or the payout of funds to your bank account. To stick with the above-mentioned metaphor, the Stripe webhook endpoint is the person answering that call and taking action based on the received information.

In practice, a Stripe webhook endpoint means some code running on your server, which can be written in PHP, Node.js, Ruby, Java, C#, just to mention a few. The Stripe webhook endpoint also has an associated URL. Stripe notifications are called Event objects, which contain all the relevant information regarding what happened, including the type of event and its associated data. The Stripe webhook endpoint uses the details of the event to take any required actions.

When you should use webhooks

Many events that happen in your Stripe account have synchronous, immediate results. For instance, a successful request to create a customer immediately returns a Customer object, and for that, you don’t need to use webhooks as the information is readily available.

However, other events are asynchronous which means these happen at a later time and not directly in response to your code’s execution, such as notifications of payouts, recurring charges of subscriptions, or invoice related notifications. For these and similar events, you will need Stripe webhooks to notify your integration about changes to the status of an object so your integration can take the necessary steps.

Actions executed by your Stripe webhook endpoint are event specific such as logging an accounting entry when a transfer is paid, making changes to an invoice when it’s created but has not been paid yet, indicating that an order can be fulfilled or updating a customer’s database information when a recurring payment succeeds.

The difference between webhooks and APIs

API is an acronym, and it stands for “Application Programming Interface”. An API is a set of functions that applications can use to access data and features. APIs can be thought of as building blocks for creating a larger system. APIs can share data or functionality, for instance, you can use a “places API” to search for restaurants by name or location, acquiring data about each place. Furthermore, you can combine that information with a “mapping API”, using it as an interface for displaying data.

Webhooks are sometimes referred to as “reverse APIs”, in the sense there is no need to initiate a request, data is sent whenever there’s new information available.

Webhook examples

Below you can see common scenarios and related events examples. These events are sent by Stripe to your webhook endpoint in response.

One-off purchases with charges

• A single one-off purchase by a given customer (charge.succeeded)
• Customer successfully purchases but then requests a refund. You’ve hit the refund button on Stripe’s dashboard to generate a refund event. (charge.succeeded; charge.refunded)
• Declined customer card: This event also describes other failures modes such as invalid expiration date or a failed CVC check. (charge.failed)
• Charge then change description: After making a charge you have the option to update description and metadata fields. (charge.succeeded; charge.updated)
• Create a charge without capturing it: In most cases, charges are “authorized” and “captured” at the same time. However, Stripe allows you to separate these two events. (charge.succeeded; charge.captured)

Read more about Stripe charges here.

Customers

• Create a new customer and charge immediately: The flow is the same as a simple charge with the added benefit of being able of charge the customer again.
• Create a customer with a plan and a free trial: This allows you to give your customers a taste of your service prior to purchasing it. In this case, Stripe creates a $0 invoice and pays it when you create the subscription for that customer.
• Create a customer with a plan but without a trial.
• Create a customer with a discounted plan but no trial: Discounted subscriptions are basically the same as conventional subscriptions with one more event.
• Customer changes card: A set of events that happens when you assign a new card to the customer’s “card” attribute. The events are similar when a card is added and the default one is changed manually, but without a “delete” event.
• Adding invoice items to existing customers: Adding invoice items for a customer without specifying an invoice automatically adds them to the next month’s invoice.

Read about Stripe customers here.

Disputes

Disputes can and do happen from time to time. Let’s say a customer disputes a charge and you upload evidence. In such case, Stripe send your application a series of webhooks as the dispute process evolves: charge.dispute.created; charge.dispute.updated; charge.dispute.closed

Read about Stripe disputes here.

We hope this article will give you an overall idea of how Stripe webhooks work. Stay tuned as we are continuously creating more content for you to learn and grow with WP Full Stripe.