What are webhooks, and how do they work?

image of smartphone with notifications, what are webhooks article

Imagine this: your organization has a television at the office that lists articles that your team has published using your content management system (CMS).

Included on the screen are headlines, times of publish, authors, and a number of other data points.

In this situation, there are presumably two systems:

  • The CMS used to create and publish the articles and their data
  • The app on the television that displays that article data

But how are the two systems able to communicate with one another to achieve the above?

One popular way is webhooks.

What are webhooks?

A term coined and promoted in 2007 by a developer named Jeff Lindsay, a webhook allows different apps to send user-defined callbacks to one another via HTTP POST requests. In plainer English, webhooks allow notifications to be sent from one app to another app when a certain event occurs. The user gets to determine which event triggers the notification, and all notifications are sent in real time.

The fact that these notifications are sent in real time is important.

Using the television/CMS example above, let's say that I'm an editor-in-chief of a publication at a news organization. It's on my shoulders to enable my team members to complete their work. As part of this effort, I need to respond to conversations they have within our CMS as quickly as possible, and that means I need to know when comments are made, even if I'm not in the CMS myself.

Without webhooks, I could have the CMS send me data about comments every thirty minutes, every three hours, etc. (a process called polling)—but if a time-sensitive comment is made in the CMS, and I don't know about it right away (and therefore don't respond to it right away), then I'm not doing my job as well as I need to be.

How do webhooks work?

Webhooks are handy when you don't have direct access to the system or app from which you are trying to receive data, just like the app running on the television didn't have access to the article metadata in the CMS.

Webhooks are typically set up by REST APIs, and both the CMS and the app in the example above have one. The app's REST API does two things:

  • It calls the CMS's REST API and tells it to send metadata over when X event occurs (let's say when an article is published)
  • It provides an endpoint (a URL) to which that metadata should be sent when X event occurs

Once this webhook is established, the app sits tight. All sorts of things go on in the CMS, and eventually, an article gets published. The CMS checks its webhooks when this happens, sees that the app has made one, and then pushes the metadata (the headline, author, time of publish, etc.) over to the URL that the app provided.

Let's walk this into a real-life example:

My young child is in daycare. It's important for me to know when she goes down for a nap so that I can adjust the time she goes to bed. I call the daycare and request that they call me at the number I provide when my daughter starts napping. This action of me calling the daycare and asking that they send me a notification when a specific event happens—that's me calling the daycare's REST API, generating the webhook, and providing the endpoint at which the daycare can return the information I requested (my phone number).

Next, I go about my workday. At 12:03 p.m., I get a call from the daycare telling me that my daughter has gone down for a nap. I now have the information I needed, I can act on it however I need to, and therefore, I enjoy the value of the webhook I established with the daycare.

It's important to note that webhook concept creator Jeff Lindsay also evangelized two other use cases for webhooks beyond the notifications discussed above:

  • Integration of different web apps (using webhooks to take data from one app, reformat it, and pass along to another app)
  • Modification of web apps (using webhooks to allow plugins or other modifications to an app depending on what that app permits)

Brightspot and webhooks

Using Brightspot, you can create webhooks in two ways. The first way is the standard way you create a webhook—through configuring APIs; however, Brightspot also allows webhooks to be easily created via its editorial UI.

Webhooks in Brightspot_1.png

In the image above, the user is able to simply navigate to a section within Brightspot CMS, select REST Management API from a dropdown list, and then see an interface with all necessary elements laid cleanly out for them.

After entering a name for the API and defining the API's URL (not the same as the webhook's URL—a conversation for another day), the user can click "Add Webhook," which pops open a content edit form where they can define the URL to which metadata is sent as well as what event triggers the webhook.

Webhooks in Brightspot_2.png

Topics are the events discussed above. Many of these come out-of-the-box with Brightspot: Publish, Conversation, Translation, Workflow—and quite a few more than those. Depending on which topic the user chooses to "listen" to, the UI morphs to add deeper configuration functionality.

From those examples alone, outside apps can receive notifications when something is published, when a comment is made in the conversation widget, when a translation has transitioned to any number of states, or when an asset progresses through a workflow.

All of this is highly actionable information for an editor.

Content filters allow me to dig down with even greater granularity as to which specific event triggers a notification. Maybe the user only wants the webhook for a particular site in their multisite environment, or maybe only for the notification to trigger the first time a specific event occurs.

All possible.

As software-as-a-service platforms continue to enjoy widespread popularity across the internet, webhooks remain a valuable way to get these platforms to communicate, and more importantly, ensure the users of these platforms are well aware of relevant changes the moment they are made. And with Brightspot, you get the tools to make webhooks however you prefer to do so.


Webhook FAQs

Webhooks provide simple yet powerful connectivity between different digital nodes, from easily programmable workplace automation tasks to more sophisticated connections between back- and front-end digital applications. To recap what we've learned in this explainer article, here's a quick snapshot of how webhooks work and the benefits that webhooks offer.

What is a webhook?

Webhooks allow different apps to send user-defined callbacks to one another via HTTP POST requests. In plainer English, webhooks allow notifications to be sent from one app to another app when a certain event occurs. The user gets to determine which event triggers the notification, and all notifications are sent in real time.

How does a webhook work?

A webhook is basically a call between two services that is triggered by an event in one system that then needs to be reported by another. When a defined event is triggered, the system in which it occurred sends data to the URL provided by the receiving system by way of an HTTP request.

What's the difference between a webhook and an API?

Though there are very specific and technical nuances, you can typically think of an API (application programming interface) as something that facilitates a two-way connection between applications—say, a CMS and third-party analytics tool—to accomplish any number of tasks: fetching data, pushing data, and the list goes on.

A webhook is an API pattern; therefore, it becomes difficult to compare and contrast the two in a traditional way. For practical purposes, consider a webhook as a simple API that pushes data from one system to another without serving any other function.

What are webhooks used for?

Webhooks are used to send information in real time between different web applications. Use cases for webhooks run the gamut from publishing alerts for internal teams to a home-grown service to alert members of a social group when a new event is added to a shared calendar.

What are some examples of a webhook?

Here are some examples of different ways a webhook can be used:
  • A digital publisher needs to be notified the moment an article is ready to be approved for publication on the website thought the company's CMS. A webhook will send an SMS alert to her phone to let her know the article is ready for final approval.
  • An eCommerce business needs to know when a new order has been received and to alert the necessary team members that this item is ready for fulfillment. A webhook can trigger an email notification to all the necessary team members as well as update the relevant workflows in the system.
  • A restaurant owner wants to know whenever a new customer review is received that is lower than two stars. A webhook can alert the owner via text that the negative review has been received and he can respond accordingly.
  • An accounts-receivable team wants to know when a vendor has submitted a new invoice through the company's shared invoicing email address. A webhook can update the appropriate accounts database with the vendor's invoicing details to ensure speedy processing of the invoice as well as consistent financial documentation.

About the Author
Mark is a Manager, Digital Content at Brightspot. When he's not gleaning insights from various developers from the company, he spends his time cooking new dishes at home with his wife and two hyperactive cats.

More from Brightspot