What are Webhooks?

Jan 22, 2014

Table of contents:

1. An API will request data
2. A Webhook will receive data
3. Why would you use a Webhook?
4. Technically, what is a Webhook?
5. What are some real life examples of Webhooks in action?
6. Conclusion

An interesting trend of the Internet from the last 10 years or so has been the evolution from static websites to real-time applications and services. It’s almost unheard of to find a new website these days that does not have some sort of real-time service component.

What do I mean by real-time service component? Well blogs usually have an RSS feed and nearly every new web application these days has an API.

API’s in particular have become increasingly popular over the last couple of years. Many web applications have public API’s that allow developers to build on top of their services. However, private API’s are probably even more popular as the rise of client side MVC type applications and mobile application has exploded.

An API is an excellent way to communicate data between separate applications. When you need to ask a question to an application an API is the perfect solution. But what if you want to be notified that something has changed? In this case an API would be extremely inefficient. Instead you need to use a Webhook.

In this post I’m going to look at Webhooks, what they are used for and how amazingly useful they can be in your applications.

An API will request data

An API is basically a way to ask a question to another separate application. For example, if I was developing an application and I wanted my users to be able to find the people they follow on Twitter, I could ask the Twitter API, “Give me a list of all of the people this user follows on Twitter”.

An API is a common interface between two different applications. In the example above, it doesn’t make a difference if I write my application in Ruby and Twitter is written in Java because the API transmits and receives data in a common format (usually JSON or XML).

This allows two totally separate applications to send and receive data.

An API is also useful when you want to take a direct action with another web service. Say for example I created an application that was built on top of Foursquare. In order for my users to use my application, they would need a Foursquare account. When they download my application I will have to either ask them to sign in with their Foursquare account or create an account if they don’t already have one. This is a direct action because the Foursquare API knows to create a new account because I have specifically asked it to.

A Webhook will receive data

So if an API is used to ask a question or make a direction request, what is a Webhook? A Webhook is basically a way to be notified when an event has occurred, usually not due to a direct action from your application.

For example, say I had created an application for my restaurant that used the Foursquare API to track when people checked in. When a user checks in with Foursquare I want to be able to greet them by name and offer them a complimentary drink.

If I was using an API I would have to be constantly asking “Is anyone here yet?” because if I didn’t ask the question I would never find out. This is very inefficient because my application would have to ask every couple of seconds and for the majority of the time the answer would probably be no.

A Webhook on the other hand would instead notify me when someone had checked in to my restaurant by sending me a request saying “Hey, Bob has just checked in”. This would allow me to run any processes I had in my application for such an event.

So an API is used to ask direct questions and a Webhook is used to be notified when certain events take place. Instead of constantly asking if anything has been changed, you can sit back and be notified when something actually has changed.

Why would you use a Webhook?

So hopefully from my example above it is clear why you would use a Webhook, but just incase it’s not, I will go over why I think you should use Webhooks and in what situations.

You should use a Webhook when you want a certain process to be initiated in your application due to an event that occurred in a separate application.

For example, say you have a subscription application and you use a payment provider like PayPal. When your customer’s subscription automatically renews you want to be notified that the payment was successful so you can update the subscription in your database.

When you require real-time notifications of events, using a Webhook is really your best option. If instead we used the PayPal API to check if a user had renewed their subscription our database would be out-of-date up until the request had been made.

Technically, what is a Webhook?

When you first learn about Webhooks, it can seem like a pretty overwhelming concept to get your head around. Surely something as powerful as distributed real-time events is technically difficult to pull off?

Well the good news is, Webhooks are incredibly easy to create, much easier than building an API.

A Webhook is basically just a POST request that is sent to a specific URL. That URL is set up to receive the body of the POST request and process it in some way.

So if you have ever created a form and submitted it in code, you know how to create a POST request. Typically you would use a HTTP library (such as Guzzle), but it is essentially the same thing.

On the receiving end you would create a URL that is set up to receive the POST request. For example, in Laravel you might do something like this:

Route::post("webhooks/stripe/delete", "StripeController@delete");

This endpoint would receive an event object in JSON or XML. This might look something like this:

{
    "id": "evt_103Ke32eZvKYlo2Cwvq3Dmp8",
    "created": 1390050235,
    "livemode": false,
    "type": "customer.deleted",
    "data": {
        "object": {
            "object": "customer",
            "created": 1390050231,
            "id": "cus_3Ke3ahsm1jlK0n",
            "livemode": false,
            "description": "abcd | 1",
            "email": "abcd@recruiterbox.com",
            "delinquent": false,
            "metadata": {},
            "subscription": null,
            "discount": null,
            "account_balance": 0,
            "currency": null,
            "cards": {
                "object": "list",
                "count": 0,
                "url": "/v1/customers/cus_3Ke3ahsm1jlK0n/cards",
                "data": []
            },
            "default_card": null
        }
    },
    "object": "event",
    "pending_webhooks": 0,
    "request": "iar_3Ke3LJSfscqR8B"
}

Your endpoint would then be able to consume this object and run any processes that you might have. In this example you might want to delete the customer from your database and send an email.

What are some real life examples of Webhooks in action?

Whenever I read an article explaining an abstract topic like this, I like to see how it is actually used in real life. I think it is difficult to totally understand something unless you can see it in real life.

With that being said, here are three companies that offer Webhooks as part of their service.

MailChimp

MailChimp offers Webhooks for a number of common events such as subscribing, unsubscribing and profile changes. This would be incredibly useful if you were using MailChimp to signup users from your website to your newsletter but you also wanted to pass that data to your CRM system.

SendGrid

SendGrid offers Webhooks that can tell you when your transactional emails are delivered, opened or if they failed to be delivered to the recipient. This would be incredibly useful if you were using SendGrid to send important emails to your users because you would know if they had not been delivered or opened so you set the wheels in motion to try to contact them again or use a different form or communication.

Stripe

Stripe offers a lot of different events that can be used as Webhooks within your application. Events such as a successful charge or a failed charge allow you to keep your records up-to-date, whereas the subscription will end event allows you to initiate the renewal process on your end which might include a notification to the user, an email or even a coupon based upon their activity.

Shopify

Shopify offers Webhooks to keep the other parts of your commerce and fulfilment system up-to-date. This could include shipping an order or updating your accounting software so you don’t have to manually enter new transaction details.

Conclusion

It’s strange that Webhooks don’t get the same kind of love that API’s do. You always here about APIs from certain web applications, but you hardly ever here about Webhooks.

The funny thing is, when you build software for internal companies that require separate applications, you will end up using Webhooks a lot! Webhooks make keeping many different services up-to-date incredibly easy and can remove a lot of the manual work of entering data that is prone to error. When consulting for large companies, Webhooks are an invaluable tool that you can call on.

I’m glad that more consumer services are adopting Webhooks. It makes sense for companies like Mailchimp, SendGrid, Stripe and Shopify to offer Webhooks, but I think it would be pretty interesting if more consumer type applications offered them too. The ability to kick start a process based upon an event in a separate application is extremely powerful and offers a glimpse at the future of the real time web.