What are webhooks?

Ever since Jack Lindsay originally coined the term webhook in 2007, people have been writing articles trying to answer the question What is a webhook? It may seem a complex question to answer, but understanding webhooks is actually much easier to grasp than you might think. Most great ideas in software come from simple and flexible ideas in real life. The same holds true for webhooks. So let me start with something we all can relate to.

Everyone loves to eat out at a restaurant at least once in while. Restaurants provide a service where customers can enjoy a (hopefully) great meal. Every restaurant offers their own unique combination of food, setting, atmosphere, and service hoping to gain you as a customer. The great restaurants work hard to make the experience so good, you can’t wait to come again.

One experience that is common to nearly every restaurant is how you are seated at a table. You walk in the door and expect to leave your information including your name, number of people in your party, and maybe a phone number. In return, you immediately hear when your table is ready. Whether you are notified by simply hearing your name called out, a buzz from a paging coaster, or a text message on your phone, you expect fast notification regarding the status of your request for a table.

Let’s look at the steps that are essential to a great experience in such an exchange.

1. First you need to register your intent to receive a notification from the restaurant when your table is ready. This registration must include some minimum information that lets the restaurant host know how to contact you.

2. Second you must receive the promised notification message from the restaurant that your table is ready.

3. Finally the restaurant expects you to return to the host and let them know you received the notification and are ready to eat!

This is basically all you need to know to understand webhooks. A web application or service is the same as the restaurant. Each one is trying to win you as a customer. Many of these web services offer methods for customers to register for event notifications that provide even more possibilities than letting you know your table is ready.

1. You must first register a public URL endpoint with the service to receive notifications. This is how the service knows how to contact you.

2. The service will send an HTTP request to your URL endpoint with a specific message containing details of the event. The specific details of the event are often referred to as the payload. You must provide the business logic (code) that understands how to handle the event.

3. You acknowledge successful receipt of the event in your response to the HTTP event request. This is typically communicated via a status code in your response.

When we talk about webhooks, we are talking about the two parties (service and customer) along with the steps in this exchange. Webhooks are a simple and flexible idea built on the powerful foundation of the Web.