Webhooks. Some developers love them, some developers hate them. Non-developers love saying it. It’s a fun word. Sounds like something Spiderman would use in a fight.

But they aren’t. They are a modern software principle used in pub/sub architectures to notify subscribers when certain events occur in a system.

Woah woah woah.

Let’s break that down a little bit. That was a lot of fancy words strung together.

To help illustrate webhooks and their purpose, we’re going to use car shopping as a metaphor.

The Problem

In spring of last year I was in the market for a new car. I really wanted a Jeep Wrangler. So I went to the internet and searched across dozens of car dealerships to see what was in stock.

Unfortunately for me, I’m pretty picky and did not like anything I saw.

So I kept going back day after day, checking if any of these dealerships had something new. Most days, nothing new would come in. Other days, a new Wrangler would come in, but it wasn’t a color or year that I was looking for.

Before I knew it, I had spent a significant amount of time asking these dealerships for the same thing over and over again.

It would be really nice to just be notified when something comes in that matches what I want.

I went into the Jeep dealer to check the lot myself. Of course, nothing matched my criteria. So I asked the dealer to give me a call whenever a red, blue, green, or yellow Jeep came in.

I stopped browsing their website every day and waited for a call. Sure enough, about two weeks later I got a call and long story short - I’m happily driving my new Wrangler.

So how does this relate to webhooks?

What Is A Webhook?

A webhook is an API that accepts data from a publisher. The publisher is triggered by an event in the software system. When an event occurs, the system makes a call to all of the subscribers who wish to be notified.

The publisher does not know what the subscribers are going to do with the information and frankly - it doesn’t care. All it cares about is notifying subscribers that something happened.

Tying this back to the car dealership, we have a few pieces.

• The publisher is the car dealer
• The subscriber is me
• The event is a Jeep matching my criteria getting in stock
• The webhook is my phone number

When I went into the car dealer, I subscribed to the “car matching my criteria” event by giving the dealer my phone number. I didn’t commit to purchasing a car or promise I would come in. It was strictly to be informed. When a car that I might be interested in rolled onto the lot, the dealer called my phone and let me know.

From there it’s up to me, the subscriber, to figure out what to do.

Getting Specific

Car dealerships turn over a lot of inventory. If I had asked to be notified any time they got a new car, my phone would have been ringing off the hook and I eventually would have stopped answering.

By adding my specific criteria when I was subscribing, I was able to weed out the noise. I was only contacted when something I specifically cared about came into stock.

Give me a red/blue/green/yellow Jeep less than 5 years old.

With webhooks, this is known as a filter. There is no “red/blue/green/yellow Jeep less than 5 years old” event from the car dealership. But there is a “new car on the lot” event.

So I subscribed to the “new car on the lot” event and added a filter of “red/blue/green/yellow color, Jeep make, Wrangler model, and < 5 years old year”.

By adding the filter, I now only receive updates I care about.

Summary

Webhooks are useful because it frees you up from constantly checking if something happened. A software system will notify you as soon as something happens. You can ask to be notified on any number of events/things happening.

You are the owner of the webhook, not the software system. The webhook is your callback number for when something happens.

Webhooks can be notified whenever a generic event happens or you can filter down to be notified when specific criteria are met.

Software systems are known as publishers. Owners of the webhook (you!) are known as subscribers. This is where the phrase pub/sub comes from.

If you wish to learn more about how systems like this work, AWS has a managed service called SNS (Simple Notification Service) that handles the hard work for you. I have also provided a quick start guide for building your own webhooks and publishing events.