The Plain-English Guide to Webhooks

Third-party web-based applications are becoming increasingly common among businesses of all sizes. They provide specialized tools and infrastructure to save time and resources, from handling monetary transactions to email automation, and so much more.

All of these interacting applications need ways of communicating efficiently, in a way that streamlines procedures and suits your needs. Consider the following example.

You run an online store that sells T-shirts. Sales are taking off, so you decide to use the third-party payment application PayNow to handle all transactions on your site. To improve customer experience, you also want your store to send confirmation emails to customers immediately after purchases with the PayNow service.

But how can PayNow, a separate application from your store, communicate to you that someone just bought a T-shirt?

One solution is to have your store app regularly request data from PayNow — say, once a minute. Then your app could email customers with the appropriate purchase info. However, that’s a lot of requests and could potentially cause issues with email deliveries. A better option would be to use a webhook.

In this post, we’ll cover what a webhook is, how it’s different from using an application programming interface (API), and how it works. Let’s get started by defining what a webhook is.

The term “webhook” merges web, as in website or web application, and hook, a programming term meaning a function that runs when another event occurs. Now that we know what a webhook is, let’s take another look at our T-shirt example.

To enable your store to communicate with PayNow, you’d set up a webhook between them, with the special event being a customer clicking the Place your order button on PayNow’s website. After this event, PayNow would send your T-shirt store app a message containing requested data, including products sold, the amount paid, and the customer’s email address. Your app would then instantly send a confirmation to the email address returned from the webhook delivery.

Your store app could do many other useful things with this information, like enter the information into a database, change a page or element on your store website (like the “popular items page”), or send you a sale notification through another application like Slack.

You might have heard of applications communicating with a similar method, known as an API request. Let’s look at the difference between these two methods below.

Webhooks vs. API

The main difference between API requests and webhooks is that API requests must manually ask for information from their provider, while webhooks are triggered automatically from the webhook provider. This is the magic of webhooks: your application never has to check for events on third-party apps.

Here’s another way you can think of it. You know how your phone automatically notifies you when you receive a new text message? That’s the way webhooks work. If these notifications were turned off, however, you’d have to check for texts yourself every few hours (or however often you decided).That’s the way API requests work.

In short, whenever you want an event on a third-party application to automatically trigger an event in your application, use webhooks.

Leading software products offer webhooks for a wide variety of uses. FourSquare includes webhooks to notify your app when someone arrives at a location. Dropbox has webhooks for notifying users when files change in their folders. And Hubspot utilizes webhooks in a variety of ways, including notifying users of important events.

Now that we understand the difference between webhooks and APIs, let’s take a more technical look at how webhooks work.

How do webhooks work?

After an event occurs on the webhook provider’s app, the webhook sends an HTTP request from the provider to the webhook receiver.

An HTTP request is essentially the provider asking to transfer information to the receiver app using a specific data format called JSON, which is accepted and interpreted by the receiver. Your receiver application framework should be able to handle these requests and turn them into useful information. The receiver then sends a second HTTP request back to the provider, telling them that their request was successful.

Here’s a graphic by Twilio that shows the process from start to finish. In this example, Twilio is using webhooks to let your application know when a user sends an SMS message to your Twilio phone number.

Source

How to Use Webhooks

After choosing a webhook to set up with a third-party service, like PayNow, you need to give that service a special URL on your website where they can send HTTP requests. This URL is essentially like a phone number or address for your app. Your webhook provider may have an open API to help you create webhooks with their service, or they may have streamlined this process for you.

After creating your webhook, you can choose which action(s) your application takes when the webhook provider sends HTTP requests your way.

Say, for example, you want to use webhooks to pull all of a contact’s data into your T-shirt store app whenever they fill out a HubSpot form on your site. You’d set up a webhook in your HubSpot workflow so that any time a contact filled out a form, HubSpot would send that contact's entire record formatted in JSON to the webhook URL. It would look something like this:

Then your app, ie. the webhook receiver, would parse the data and use it for its own application.

Because webhooks send HTTP requests to a publicly-available URL in your application, it’s important to verify that incoming requests are safe. Many options exist for authenticating webhook requests, including HTTP basic access authentication, a signature or token sent with the request, or manually whitelisting unsafe domains.

Your webhook provider likely has documentation detailing its authentication protocol for HTTP requests. Check out HubSpot’s documentation for an example.

Using Webhooks on Your Site

If you use a third-party service with your web applications, webhooks are a valuable tool for increasing your application’s efficiency and reducing opportunities for errors. Understanding webhooks and incorporating them in your backend can help improve your processes, services, and perhaps your T-shirt sales!