What is a webhook? Everything you need to know.

Whether you're a developer, a product manager, or just someone interested in APIs, you've probably heard about webhooks before.
But what are they?
Why are they useful?
When should you use/not use webhooks?
Keep reading to learn everything you need to know about webhooks.

Introduction to Webhooks

Webhooks, also known as HTTP callbacks, are a way for APIs to automatically notify applications when a specific event occurs, without the application having to initiate a request. This enables real-time communication between different web services, where the server pushes notifications once predetermined conditions are met.

Normally, if you want information from a server, you send an API request and the server responds. But what if you don't know when the information you want will be available? You would have to send requests over and over until the information is available. This approach is called API polling.

An analogy that we like to use when explaining webhooks is a family on a road trip. If you have young children and have taken them on a road trip, you'll know all too well the pain that comes when they start asking "Are we there yet?" (or maybe you have childhood memories of annoying the crap out of your parents). It's not really their fault. They're eagerly anticipating reaching the destination and sitting in a car for hours on end is pretty boring.

This situation is a lot like API polling. Sending requests over and over again until something happens.

Now consider the alternative:

Kids are asleep or quietly reading a book or most likely playing games or watching YouTube on their iPad. You get to drive in peace and announce that you've arrived at your destination. Sounds way better right?

Webhooks are chill. No repeated requests, you just let people know when something happens.

Anatomy of a Webhook

Fundamentally a webhook is just an HTTP POST request. But instead of a client making a request to a server when they want information, the client provides an endpoint URL where they would like to receive notifications and the server sends notifications when appropriate.

Like normal API requests, webhooks are made up of headers and a payload. Headers usually contain important information for securing and verifying the request, such as signatures and timestamps that ensure the integrity and authenticity of the webhook. The payload is the body of the request, carrying the data related to the event that triggered the webhook. Event types are frequently part of the payload and specifies the nature of the event that initiated the notification, allowing the client to understand and react appropriately to different kinds of information sent by the server.

Popular Use Cases

Now that we have a good idea of what webhooks are, lets go over some of the most common ways they're used in practice.

Generally, most people talking about webhooks are talking about receiving webhooks. One of the most popular services with a high webhook adoption is Stripe. Reeiving a payment is a common trigger to initiate various workflows (e.g. enable access to premium features).

While its common to receive webhooks on your own endpoint, it's also popular to send webhook messages to other services. For example, you might want to send your Stripe webhook to Slack and automatically post a message in a #sales channel.

Webhooks are very popular with Fintech products but there is also significant adoption in Logistics, AI, and many other types of products. You can imagine wanting to initiate workflows based on when an invoice is paid, a contract is signed, a model finishes training, a delivery is made or a support ticket is filed. The possibilities are endless!

When Not to Use Webhooks

Webhooks are very good at what they do but there are specific use cases where other technologies would be a better solution. Remember that webhooks are a one way server to server communication method. Naturally, any scenario that requires two way communications (e.g. multiplayer games, chat) are usually handled by websockets or .

Another scenario where webhooks may not be the best solution is when there is a high volume stream of events. Webhooks are a good alternative to API polling because you don't have to make a bunch of API calls that return nothing. If there is such a high volume that every polling request returns multiple events, you would effectively be batching requests. There are also tools like Kafka and EventBridge that are purpose built for high volumes of events.

More Resources

If this introduction to webhooks wasn't actually everything you needed (or wanted) to know, we have several other resources that dive deeper into specific implementation details.

For best practices:

Webhook Security
Webhook Authentication
Webhook Retries
Best Practices for Receiving Webhooks
Best Practicses for Sending Webhooks

For guides and tutorials:

Sending Webhooks with Python
Sending Webhooks with Javascript
Receive Webhooks with Python
Receive Webhooks with Javascript

For a deep dive on architecting a webhook system:

Webhook Architecture Diagram
Standard Webhooks