What are Webhooks? — Simple English Explanation on How Apps Communicate

Imagine building a membership website and choosing to use Stripe as your credit card payment processor. Everything is great until one of your customer’s credit cards expires, causing them to miss a payment for your membership website.

If your website is never notified, you might not ever suspend their account, and they may still be able to access your site without paying. How can your system become aware that they missed a payment?

That’s where Webhooks can come in handy. Let’s take a deeper look and break things down.

What is Webhooks Used For?

In the example above, Stripe needs to “communicate” to your web app that someone didn’t pay their monthly membership fee because their credit card expired and who they are. Webhooks are then used to make sure that this communication can occur.

Webhooks are just one of a few ways (ex. polling APIs, WebSockets, etc.) for web applications to communicate with each other. A Webhook could help Stripe “communicate” to your membership website app that someone missed their payment in the above example.

Webhooks is Event-Driven

Someone missing a payment for your membership website is an event. You don’t know exactly when the event will happen, but it’s an event that can happen at any time.

However, whenever that event does happen, it will kick off a request to a Webhook URL (more on Webhook URLs later), and your code can react to the event. The event drives the Webhook request to happen, which is why Webhooks is an event-driven programming technique.

If you want to “listen” to events that are happening in other applications, Webhooks is going to help you.

How Webhooks Work

To get Webhooks to work, you would generally follow these 4 steps:

1. Register a URL with the web app you want to communicate with.
2. Receive notifications from the web app you wish to communicate with.
3. Use functions to mold the data your web app receives.
4. Send back a response to the sender.

Let’s go over it.

1. Register a URL

The first step is registering a Webhook URL with the 3rd-party app you would like to listen to.

The receiving web app provides a Webhook URL. It almost acts as a “phone number” that the sending application can “call” when an event happens.

One such 3rd-party app that you can use Webhooks with is Stripe. Imagine that you are building a membership website and use Stripe to handle the monthly subscription payments. Whenever a user’s credit card expires and causes a payment to fail, you want Stripe to let your web app know which URL to “communicate” with to let our backend server know that the payment failed. We call this URL that receives the notification from Stripe the “Webhook URL.”

Stripe will send us the Customer ID of whose credit card failed, which we can use to look up which user it belongs to in our database. From there, we can lock the user out of their account until they have paid.

For example, if I own sunnychopper.com and want to know if someone hasn’t paid for their membership, I can create an API endpoint with the URL being something like sunnychopper.com/api/webhooks/failed-payment and have some code that handles the failed payment. From there, I would go to Stripe and let Stripe know that they should send an HTTP request to my URL, sunnychopper.com/api/webhooks/failed-payment , whenever there’s a failed payment.

Whenever an event happens that I want to listen to, Stripe will send me an HTTP request with whatever structure it specifies in the documents.

Each web app, like Stripe, will send you data in JSON or XML format when an event occurs. I recommend you view your target app’s documentation for more details.

Your web app needs to parse and read to do something meaningful whenever an event occurs.

For example, if Stripe sends you a customer_id whenever the failed payment event occurs, you need to be able to read the JSON or XML, get the customer_id and match it to a user in your database.

2. Receive Notifications from the Web App

On the backend side of your application, you want to be “listening” to events happening that are defined by the Webhook URLs that you register.

If sunnychopper.com/api/webhooks/failed-payment is defined as a Webhook URL, whenever a failed payment occurs, I need to make sure that I have some backend function for that URL that is “listening” for a failed payment and executes some backend functionality.

Whenever there is a failed payment, that Webhook URL will be sent a POST request with some information about what happened. The backend code will then have to read the inputs and decided what to do from there.

3. Mold the Data from the Webhook

The data that a Webhook sends you may have portions that are important and others that are not important. It is your duty as the developer to figure out which data you must use to accomplish a task given your goals.

You may receive data that you need to use to get more information via another API call. For example, if Stripe sends you a Customer ID after a failed payment and you cannot match it to a user in your database, you can create another request to Stripe’s API to get more information.

4. Send Response Back to Sender

Finally, the sender of the event wants to know whether you got the notification or not. You can let the sender know by returning a JSON response with a successful HTTP error code.

You may need to make some code adjustments to get the code ready for deployment. However, at this stage, the code adjustments are minor and really only about package differences in operating systems.

Whenever you receive a message from a Webhook URL, you want to send a notification back with a 200 HTTP status code denoting that it was successful.

Conclusion

Webhooks allow your web application to communicate with other web applications. We no longer have to use expensive techniques such as polling to figure out whether or not some data has been updated. This allows us to build much more efficient web applications.

You generally will have to register a URL with the application you wish to receive data from. From there, you can receive data from the third-party app via the Webhook URL. This allows us to “listen” to events happening in web apps across the internet.